Quickstart

Follow the steps below to get started with the Agent Connect Framework which will enable your agent to integrate with watsonx Orchestrate.

Enable your agent for collaboration

To make your agent compatible with watsonx Orchestrate, you need to implement the Agent Connect API endpoints. The primary endpoint is the chat completion endpoint, which follows the OpenAI chat completions format.

Step-by-step example

Set up your server

First, create a server that will host your agent’s API endpoints. You can use any web framework in your preferred language. Here are a few examples using Express.js, Flask and Go’s standard library:

const express = require('express');
const app = express();
app.use(express.json());

const PORT = process.env.PORT || 3000;

app.listen(PORT, () => {
    console.log(`Agent server running on port ${PORT}`);
});

Implement the chat completion endpoint

Add the chat completion endpoint to your server:

app.post('/v1/chat', async (req, res) => {
    try {
    const { messages, stream = false } = req.body;
    
    // Get thread ID from header if present (for stateful conversations)
    const threadId = req.headers['x-thread-id'] || 'default';
    
    if (stream) {
        // Set up SSE streaming
        res.setHeader('Content-Type', 'text/event-stream');
        res.setHeader('Cache-Control', 'no-cache');
        res.setHeader('Connection', 'keep-alive');
        
        // Process messages and stream response
        await streamResponse(res, messages, threadId);
    } else {
        // Process messages and return complete response
        const response = await processMessages(messages, threadId);
        res.json(response);
    }
    } catch (error) {
    console.error('Error processing chat request:', error);
    res.status(500).json({ error: 'Internal server error' });
    }
});

Implement the agent discovery endpoint

Add the agent discovery endpoint to allow your agent to be discovered:

app.get('/v1/agents', (req, res) => {
    res.json({
        agents: [
        {
            name: 'My Custom Agent',
            description: 'A specialized agent that helps with specific tasks',
            provider: {
            organization: 'Your Organization',
            url: 'https://your-organization.com'
            },
            version: '1.0.0',
            capabilities: {
            streaming: true
            }
        }
        ]
    });
});

Implement message processing logic

Create functions to process messages and generate responses:

async function processMessages(messages, threadId) {
    // Your agent's logic to process messages and generate a response
    // This is where you would integrate with your LLM, tools, etc.

    const response = {
        id: generateId(),
        object: 'chat.completion',
        created: Math.floor(Date.now() / 1000),
        model: 'your-agent-model',
        choices: [
        {
            index: 0,
            message: {
            role: 'assistant',
            content: 'This is a response from your agent.'
            },
            finish_reason: 'stop'
        }
        ],
        usage: {
        prompt_tokens: 0,
        completion_tokens: 0,
        total_tokens: 0
        }
    };

    return response;
}

async function streamResponse(res, messages, threadId) {
    // Example of streaming a response with thinking steps and tool calls

    // Stream thinking step
    const thinkingStep = {
        id: `step-${generateId()}`,
        object: 'thread.run.step.delta',
        thread_id: threadId,
        model: 'your-agent-model',
        created: Math.floor(Date.now() / 1000),
        choices: [
        {
            delta: {
            role: 'assistant',
            step_details: {
                type: 'thinking',
                content: 'Analyzing the user request and determining the best approach...'
            }
            }
        }
        ]
    };

    res.write(`event: thread.run.step.delta\n`);
    res.write(`data: ${JSON.stringify(thinkingStep)}\n\n`);

    // Wait a moment to simulate processing
    await new Promise(resolve => setTimeout(resolve, 1000));

    // Stream final message
    const messageChunk = {
        id: `msg-${generateId()}`,
        object: 'thread.message.delta',
        thread_id: threadId,
        model: 'your-agent-model',
        created: Math.floor(Date.now() / 1000),
        choices: [
        {
            delta: {
            role: 'assistant',
            content: 'This is a streamed response from your agent.'
            }
        }
        ]
    };

    res.write(`event: thread.message.delta\n`);
    res.write(`data: ${JSON.stringify(messageChunk)}\n\n`);

    // End the stream
    res.end();
}

function generateId() {
    return Math.random().toString(36).substring(2, 15);
}

Deploy your agent

Deploy your agent to a publicly accessible URL. You can use platforms like:

IBM Cloud Code Engine
AWS Lambda
Google Cloud Run
Your own infrastructure

Ensure your agent is accessible via HTTPS for security.

Using an open source agent framework?

Check out our examples for ideas on how to use popular open source frameworks with Agent Connect.

To connect your agent with watsonx Orchestrate, you need to log in to an IBM watsonx Orchestrate account.

If you already have an account set up, log in to watsonx Orchestrate .
If you don’t have an account, you can sign up for a watsonx Orchestrate free trial:
- Visit the watsonx Orchestrate free trial page and follow the instructions to sign up.