Local set up

This guide walks you through setting up your local environment for Bridge agent development.

Create your repository

Go to bdg-sw-agents-bridge-agent-template

Click Use this template → Create a new repository

Configure:

Owner: kyndryl-agentic-ai

Repository name: bdg-sw-agents-{{your-agent-name}}

Visibility: Private

Click Create repository

JFrog Artifactory authentication

The Bridge Agent SDK is hosted on a private JFrog Artifactory repository. Get JFrog API Token

Go to https://kyndryl.jfrog.io

Click your User Profile (top right) → Edit Profile.

Under Authentication Settings, click Generate an Identity Token.

Copy the generated token.

Configure Authentication (.netrc - recommended)

Create or edit ~/.netrc file:

# Create .netrc file
cat >> ~/.netrc << 'EOF'
machine kyndryl.jfrog.io
login [email protected]
password your-jfrog-api-token
EOF
# Secure the file (required)
chmod 600 ~/.netrc

Security note: Never commit .netrc to version control.

Install dependencies

Activate your virtual environment: source venv/bin/activate

Install all dependencies (SDK from Artifactory): pip install -r requirements.txt

Install test dependencies: pip install -r requirements-test.txt

Verify SDK Installation

from bridge_agent_sdk import BridgeBaseAgent, 
BridgeBaseWorkflowAgent, create_llm_client
print('✅ Bridge Agent SDK installed successfully!')"

Runtime modes

The SDK supports three runtime modes controlled by the KAIF_MODE environment variable:

Mode	Description	Use case
local_dev	No Bridge Platform access. LLM calls go directly to OpenAI. Token/credentials are stubbed locally.	Local development without VPN
bridge_dev	Bridge Platform available at dev URLs. All services route through gateways.	Development with Bridge access
production	Full Bridge Platform integration. All payload fields required.	Production deployment

Configure environment

Option A: local_dev + OpenAI (default - fastest start)

Use this when you have a standard OpenAI API key and want the fastest path to running your agent.

Create .env file:

KAIF_MODE=local_dev

LLM_PROVIDER=openai

LLM_MODEL=gpt-4.1-min

OPENAI_API_KEY=sk-your-openai-api-key-here

OPENAI_API_BASE=https://api.openai.com/v1

Get your key: https://platform.openai.com/api-keys

Option B: local_dev + Azure OpenAI

Use this when your organization provides Azure OpenAI resources.

KAIF_MODE=local_dev

LLM_PROVIDER=azure_openai

LLM_MODEL=gpt-4.1-mini

AZURE_OPENAI_ENDPOINT=https://my-resource.openai.azure.com

AZURE_OPENAI_API_KEY=your-azure-api-key

AZURE_OPENAI_API_VERSION=2024-02-01

AZURE_OPENAI_DEPLOYMENT=my-gpt4-deployment

AZURE_OPENAI_DEPLOYMENT is the deployment name you created in Azure Portal, not the model name. If omitted, the SDK uses LLM_MODEL as the deployment name

Option C: local_dev + hosted LLM (custom endpoint)

Use this for any OpenAI-compatible endpoint that uses non-standard auth (e.g. internal proxy, Kyndryl-hosted LLM).

KAIF_MODE=local_dev

LLM_PROVIDER=hosted_ll

HOSTED_LLM_BASE_URL=https://integration.chatops.kyndryl.net/v1

HOSTED_LLM_AUTH_HEADER=Bearer your-token-or-api-key

HOSTED_LLM_MODEL=my-custom-model

# Optional extra HTTP headers (JSON)

# HOSTED_LLM_EXTRA_HEADERS={"X-Team": "my-team"}

You do NOT need OPENAI_API_KEY for the hosted_llm provider - the SDK sets openai_api_key="none" internally and uses the Authorization header from HOSTED_LLM_AUTH_HEADER.

Option D: bridge_dev mode (with Bridge Platform)

Use this when you have access to Bridge Platform and need to test with real LLM Gateway, MCP tools, and platform services.

KAIF_MODE=bridge_dev

KAIF_HOST=https://dev1-aws-oregon-base.bridge.kyndryl.com

SERVICE_API_KEY=your-service-api-key

BRIDGE_ACCOUNT_ID=your-account-id

bridge_dev: What You Get

LLM_MODEL=gpt-4.1-mini

SERVICE_API_KEY is mandatory in bridge_dev mode, the SDK will crash on startup if it is missing.

In bridge_dev mode, all services route through KAIF_HOST:

Verify setup

Test local_dev + OpenAI. See Open AI

Test local_dev + hosted LLM. See hosted LLM

Test bridge_dev mode. See testing

Run your agent

# local_dev - direct execution
KAIF_MODE=local_dev python main.py
# bridge_dev - with --execution_context CLI arg (platform-style invocation)
KAIF_MODE=bridge_dev python main.py --agent_name my_agent --execution_context '{"agent_data":{"content":"test"},"system_data":{"metadata":{"workflow_id":"wf-1","account_id":"acc-1","instance_name":"test","agent_id":"test","user_id":"u1","session_id":"s1"},"connection_details":[],"timeout":1800,"type":"interactive"},"runtime_data":{}}'

Run Tests

pytest tests/ -v