Add Integrations in OpenServ

A Developer's Guide for understanding how to add third party integrations in OpenServ

Integrations are a core part of building useful AI agents. They connect your agents to external services and data sources, allowing them to perform actions in the real world. This guide explains how integrations work in OpenServ and introduces the powerful Model Context Protocol (MCP) integration system.

YouTube video of Armağan Amcalar, OpenServ CTO, explaining the three distinct ways developers can implement third-party integrations on the OpenServ platform

Integrations in OpenServ: 3 Approaches

OpenServ offers three different ways to use integrations, giving you the flexibility to choose the right approach for your needs:

Approach A: using OpenServ native integrations

https://youtu.be/6q113_nF5Qsyoutu.be

OpenServ offers several native integrations that work out-of-the-box:

• Google Workspace: Access to Gmail, Google Calendar, and more

• Twitter/X: Post tweets, read timeline, and interact with the platform

• YouTube: Upload videos and descriptions

• Slack: Send messages, create channels, and interact with workspaces

... and others.

This is the simplest approach, as you will use OpenServ native integrations. All you need to do is add it to your agent scope.

The screenshot shows our native integrations which a developer can add to their agent by just clicking the Add Scope button

With this approach:

• OpenServ handles the entire integration process

• Your agent just receives the data it needs

• The platform manages authentication, API calls, and data transformation

• You focus on implementing your domain expertise

Approach B: Text-Based Requests

This more flexible approach lets you describe what you need in natural language:

This example is being baked 🍞 and will be available soon!

This approach:

• Uses natural language to specify what you need

• Provides more flexibility than the fully managed approach

• Still handles all the integration complexity for you

• Works well when your requirements are straightforward but dynamic

Approach C: Direct API Control

For advanced developers who need precise control:

DexScreener APi Example

// See the full code on our example repo 
// https://github.com/openserv-labs/agent-examples/blob/main/dexscreener-analytics/index.ts 

const dexScreenerAnalyticsAgent = new Agent({
  // Describe with natural language
  systemPrompt: 'You are a helpful assistant that provides up to date information about tokens.'
})

dexScreenerAnalyticsAgent.addCapability({
  name: 'filterTokens',
  description: 'Filter tokens by specific criteria',
  schema: z.object({
    chain: z.string().optional().describe('Filter tokens by blockchain (e.g., "solana", "ethereum", "bsc")'),
    minVolume24h: z.number().optional().describe('Minimum 24-hour trading volume in USD'),
    minLiquidity: z.number().optional().describe('Minimum liquidity in USD'),
    minMarketCap: z.number().optional().describe('Minimum market capitalization in USD'),
    maxMarketCap: z.number().optional().describe('Maximum market capitalization in USD'),
    maxAgeDays: z.number().optional().describe('Maximum age of the token pair in days')
  }),
  async run({ args }) {
    try {
      // Using axios to make the DexScreener API Endpoint call
      const response = await axios.get('https://api.dexscreener.com/token-boosts/top/v1')
      const boostedTokens = response.data as BoostedToken[]

      // ...

Perplexity API Example

// See the full code on our agent examples repo
// https://github.com/openserv-labs/agent-examples/blob/main/perplexity-sonar-pro/README.md

// Using axios to create communication with the Perplexity API client.ts
import axios from 'axios'

export class PerplexityClient {
  private apiKey: string
  private baseURL = 'https://api.perplexity.ai'

  constructor(apiKey: string) {
    this.apiKey = apiKey
  }

  async search(query: string): Promise<ChatCompletionResponse> {
    try {
      const response = await axios.post(
        `${this.baseURL}/chat/completions`,
        {
          model: 'sonar-pro',
          messages: [
            {
              role: 'system',
              content: 'Be precise and concise.'
            },
            {
              role: 'user',
              content: query
            }
          ],
          temperature: 0.2,
          top_p: 0.9,
          return_citations: true,
          return_related_questions: false,
          search_recency_filter: 'month'
        },
        {
          headers: {
            Authorization: `Bearer ${this.apiKey}`,
            'Content-Type': 'application/json'
          }
        }
      )

      return response.data
    } catch (error) {
      if (axios.isAxiosError(error)) {
        throw new Error(`Perplexity API error: ${error.response?.data?.message || error.message}`)
      }
      throw error
    }
  }
}

// Than just add it to your agent capability index.ts

const perplexityClient = new PerplexityClient(process.env.PERPLEXITY_API_KEY)

// Create the agent
const agent = new Agent({
  systemPrompt: 'You are an agent that searches for information using Perplexity Sonar Pro API',
})

// Add search capability
agent.addCapability({
  name: 'search',
  description: 'Search for information using Perplexity Sonar Pro API',
  schema: z.object({
    query: z.string()
  }),
  async run({ args }) {
    const result = await perplexityClient.search(args.query)
    const citations = result.citations || []
    let content = result.choices[0].message.content

    if (citations.length > 0) {
      content += `\n\Citations:\n${citations.map((url, index) => `[${index + 1}] ${url}`).join('\n')}`
    }

    return content
  }
})

This approach:

• Gives you complete control over API endpoints and parameters

• Routes through OpenServ's security layer (no need to handle auth yourself)

• Works best when you have specific integration requirements

• Is ideal for developers familiar with the third-party API