Skip to content

quickstart.md

Latest commit

 

History

History
178 lines (129 loc) · 4.38 KB

quickstart.md

File metadata and controls

178 lines (129 loc) · 4.38 KB

AI SDK - Quick Start

Get started with the AI SDK in under 5 minutes.

Prerequisites

You need:

  1. An OpenMetadata or Collate instance with Dynamic Agents enabled
  2. A Bot JWT token for API authentication

If you don't have a token yet, see Getting Your Credentials in the main documentation.

Installation

pip install data-ai-sdk

Set Environment Variables

# Your OpenMetadata/Collate server URL
# Examples:
#   Collate Cloud: https://your-org.getcollate.io
#   Self-hosted:   https://openmetadata.yourcompany.com
export AI_SDK_HOST="https://your-org.getcollate.io"

# Your bot's JWT token (from Settings > Bots in your instance)
# This is a long base64-encoded string starting with "eyJ..."
export AI_SDK_TOKEN="eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Note: Never commit tokens to version control. Use environment variables, .env files (with .gitignore), or secrets management.

Basic Usage

from ai_sdk import AISdk, AISdkConfig

# Create client from environment
config = AISdkConfig.from_env()
client = AISdk.from_config(config)

# Invoke an agent
response = client.agent("DataQualityPlannerAgent").call(
    "What data quality tests should I add?"
)

print(response.response)
client.close()

Multi-Turn Conversation

from ai_sdk import Conversation

conv = Conversation(client.agent("DataQualityPlannerAgent"))

print(conv.send("Analyze the customers table"))
print(conv.send("Create tests for the issues you found"))

Streaming

for event in client.agent("SqlQueryAgent").stream("Generate a query"):
    if event.type == "content":
        print(event.content, end="", flush=True)

Async

import asyncio

async def main():
    client = AISdk.from_config(
        AISdkConfig.from_env(enable_async=True)
    )
    response = await client.agent("MyAgent").acall("Hello")
    print(response.response)
    await client.aclose()

asyncio.run(main())

Management APIs

The SDK also supports creating and managing resources:

# List bots, personas, and abilities
bots = client.bots.list()
personas = client.personas.list()
abilities = client.abilities.list()

# Create a persona
from ai_sdk.models import CreatePersonaRequest
persona = client.personas.create(CreatePersonaRequest(
    name="MyPersona",
    description="A helpful analyst",
    prompt="You are a helpful data analyst..."
))

# Create an agent
from ai_sdk.models import CreateAgentRequest
agent = client.agents.create(CreateAgentRequest(
    name="MyAgent",
    description="Custom agent",
    persona="MyPersona",
    api_enabled=True,
))

Next Steps

Troubleshooting

"Missing AI_SDK_HOST environment variable"

You haven't set the required environment variables. Run:

export AI_SDK_HOST="https://your-org.getcollate.io"
export AI_SDK_TOKEN="your-jwt-token"

"Authentication failed" or 401 error

Your JWT token is invalid or expired. Generate a new one:

  1. Go to Settings > Bots in your OpenMetadata/Collate instance
  2. Select your bot and regenerate the token
  3. Update your AI_SDK_TOKEN environment variable

"Agent not found" or 404 error

The agent name doesn't exist or isn't API-enabled:

  1. Check the exact agent name (case-sensitive)
  2. Verify the agent exists in your instance under AI Studio
  3. Ensure "API Enabled" is turned on for the agent

"Agent not enabled for API access" or 403 error

The agent exists but isn't enabled for API use:

  1. Go to AI Studio in your OpenMetadata/Collate instance
  2. Edit the agent
  3. Enable the "API Enabled" toggle
  4. Save the agent

SSL certificate errors

If using self-hosted OpenMetadata with self-signed certificates:

client = AISdk(
    host="https://your-server.com",
    token="your-token",
    verify_ssl=False  # Disable SSL verification (not recommended for production)
)

Or set the environment variable:

export AI_SDK_VERIFY_SSL="false"

Need Help?