Python SDK API

Complete API reference for the AIP Python SDK.

📚 Overview

The AIP Python SDK provides a clean, type-safe interface for building AI applications. The main entry point is the Client class, which provides access to all SDK functionality.

🚀 Quick Start

from glaip_sdk import Client

# Initialize client (automatically loads environment variables)
client = Client()

# Create and run an agent
agent = client.create_agent(
    name="my-agent",
    instruction="You are a helpful AI assistant."
)
response = agent.run("Hello!")
agent.delete()

🔧 Client Class

Client(**kwargs)

Main client that composes all specialized clients and shares one HTTP session.

Parameters:

  • **kwargs: Configuration options passed to BaseClient

Example:

from glaip_sdk import Client

# Basic initialization
client = Client()

# With custom configuration
client = Client(
    api_url="https://your-api.com",
    api_key="your-api-key",
    timeout=60
)

🤖 Agent Management

Create Agent

create_agent(**kwargs) -> Agent

Create a new AI agent.

Parameters:

  • name (str, required): Human-readable agent name

  • instruction (str, required): System prompt/instructions (minimum 10 characters)

  • model (str, optional): Language model to use (default: "gpt-4.1")

  • tools (list[str | Tool], optional): List of tool IDs or Tool objects

  • agents (list[str | Agent], optional): List of agent IDs or Agent objects

  • timeout (int, default: 300): Agent timeout in seconds

  • **kwargs: Additional agent configuration

Returns:

  • Agent: The created agent instance

Example:

agent = client.create_agent(
    name="math-tutor",
    instruction="You are a patient math tutor. Explain concepts clearly.",
    model="gpt-4",
    timeout=600
)

List Agents

list_agents() -> list[Agent]

Get all available agents.

Returns:

  • list[Agent]: List of agent objects

Example:

agents = client.list_agents()
for agent in agents:
    print(f"{agent.name}: {agent.instruction}")

Get Agent by ID

get_agent_by_id(agent_id: str) -> Agent

Get a specific agent by ID.

Parameters:

  • agent_id (str): Agent identifier

Returns:

  • Agent: Agent object

Example:

agent = client.get_agent_by_id("agent-123")
print(agent.instruction)

Find Agents

find_agents(name: str | None = None) -> list[Agent]

Search for agents by name.

Parameters:

  • name (str, optional): Name to search for

Returns:

  • list[Agent]: List of matching agents

Example:

math_agents = client.find_agents("math")
tutor_agents = client.find_agents("tutor")

Update Agent

update_agent(agent_id: str, update_data: dict | None = None, **kwargs) -> Agent

Update an existing agent.

Parameters:

  • agent_id (str): Agent identifier

  • update_data (dict, optional): Dictionary of updates

  • **kwargs: Individual field updates

Returns:

  • Agent: Updated agent object

Example:

updated_agent = client.update_agent(
    "agent-123",
    instruction="Updated instructions",
    timeout=900
)

Delete Agent

delete_agent(agent_id: str) -> None

Delete an agent by ID.

Parameters:

  • agent_id (str): Agent identifier

Example:

client.delete_agent("agent-123")

Run Agent

run_agent(agent_id: str, message: str, **kwargs) -> str

Run an agent with a message.

Parameters:

  • agent_id (str): Agent identifier

  • message (str): Input message for the agent

  • files (list[str | BinaryIO], optional): Files to upload with the message

  • tty (bool, default: False): Enable TTY mode

  • stream (bool, default: True): Enable streaming output

  • renderer (str, optional): Output renderer ("auto", "json", "markdown", "plain")

  • verbose (bool, default: False): Enable verbose output

  • **kwargs: Additional run options

Returns:

  • str: Agent response

Example:

response = client.run_agent(
    "agent-123",
    "What is 2 + 2?",
    timeout=60,
    renderer="json"
)

🛠️ Tool Management

Create Tool

create_tool(**kwargs) -> Tool

Create a new tool from a local Python file.

Parameters:

  • name (str, optional): Tool name (auto-detected from file if not provided)

  • file_path (str, optional): Path to the Python file containing the tool

  • tool_file (str, optional): Alternative to file_path

  • tool_script (str, optional): Tool script content as string

  • code (str, optional): Alternative to tool_script

  • description (str, optional): Tool description

  • tool_type (str, default: "custom"): Tool type

  • framework (str, default: "langchain"): Tool framework

  • **kwargs: Additional tool attributes

Returns:

  • Tool: The created tool instance

Example:

# Create tool from local file
tool = client.create_tool(
    name="calculator",
    file_path="calculator_tool.py",
    description="Math calculator tool"
)
print(f"Created tool: {tool.name} (ID: {tool.id})")

Note: The tool file must contain a class with the @tool_plugin decorator and inherit from BaseTool. The backend will validate and process the tool code.

Create Tool from Code

create_tool_from_code(name: str, code: str, framework: str = "langchain") -> Tool

Create a new tool plugin from code string.

Parameters:

  • name (str): Name for the tool

  • code (str): Python code containing the tool plugin

  • framework (str, default: "langchain"): Tool framework

Returns:

  • Tool: The created tool instance

Example:

tool_code = '''
from gllm_plugin.tools import tool_plugin
from langchain_core.tools import BaseTool

@tool_plugin(version="1.0.0")
class CalculatorTool(BaseTool):
    name = "calculator"
    description = "Basic math operations"
    
    def _run(self, expression: str) -> str:
        return str(eval(expression))
'''

tool = client.create_tool_from_code("calculator", tool_code)

List Tools

list_tools() -> list[Tool]

Get all available tools.

Returns:

  • list[Tool]: List of tool objects

Example:

tools = client.list_tools()
for tool in tools:
    print(f"{tool.name}: {tool.description}")

Get Tool by ID

get_tool_by_id(tool_id: str) -> Tool

Get a specific tool by ID.

Parameters:

  • tool_id (str): Tool identifier

Returns:

  • Tool: Tool object

Example:

tool = client.get_tool_by_id("tool-123")
print(tool.get_script())

Find Tools

find_tools(name: str | None = None) -> list[Tool]

Search for tools by name.

Parameters:

  • name (str, optional): Name to search for

Returns:

  • list[Tool]: List of matching tools

Example:

math_tools = client.find_tools("math")
calc_tools = client.find_tools("calculator")

Update Tool

update_tool(tool_id: str, **kwargs) -> Tool

Update an existing tool.

Parameters:

  • tool_id (str): Tool identifier

  • **kwargs: Tool updates

Returns:

  • Tool: Updated tool object

Example:

updated_tool = client.update_tool(
    "tool-123",
    description="Updated description"
)

Delete Tool

delete_tool(tool_id: str) -> None

Delete a tool by ID.

Parameters:

  • tool_id (str): Tool identifier

Example:

client.delete_tool("tool-123")

Install Tool

install_tool(tool_id: str) -> bool

Install a tool.

Parameters:

  • tool_id (str): Tool identifier

Returns:

  • bool: True if successful, False otherwise

Example:

success = client.install_tool("tool-123")
if success:
    print("Tool installed successfully")

Uninstall Tool

uninstall_tool(tool_id: str) -> bool

Uninstall a tool.

Parameters:

  • tool_id (str): Tool identifier

Returns:

  • bool: True if successful, False otherwise

Example:

success = client.uninstall_tool("tool-123")
if success:
    print("Tool uninstalled successfully")

🔌 MCP Management

Create MCP

create_mcp(**kwargs) -> MCP

Create a new MCP connection.

Parameters:

  • **kwargs: MCP configuration

Returns:

  • MCP: Created MCP object

Example:

mcp = client.create_mcp(
    name="weather-service",
    description="Weather API integration"
)

List MCPs

list_mcps() -> list[MCP]

Get all available MCPs.

Returns:

  • list[MCP]: List of MCP objects

Example:

mcps = client.list_mcps()
for mcp in mcps:
    print(f"{mcp.name}: {mcp.description}")

Get MCP by ID

get_mcp_by_id(mcp_id: str) -> MCP

Get a specific MCP by ID.

Parameters:

  • mcp_id (str): MCP identifier

Returns:

  • MCP: MCP object

Example:

mcp = client.get_mcp_by_id("mcp-123")
print(mcp.config)

Find MCPs

find_mcps(name: str | None = None) -> list[MCP]

Search for MCPs by name.

Parameters:

  • name (str, optional): Name to search for

Returns:

  • list[MCP]: List of matching MCPs

Example:

weather_mcps = client.find_mcps("weather")
api_mcps = client.find_mcps("api")

Update MCP

update_mcp(mcp_id: str, **kwargs) -> MCP

Update an existing MCP.

Parameters:

  • mcp_id (str): MCP identifier

  • **kwargs: MCP updates

Returns:

  • MCP: Updated MCP object

Example:

updated_mcp = client.update_mcp(
    "mcp-123",
    description="Updated description"
)

Delete MCP

delete_mcp(mcp_id: str) -> None

Delete an MCP by ID.

Parameters:

  • mcp_id (str): MCP identifier

Example:

client.delete_mcp("mcp-123")

🌐 Language Models

List Language Models

list_language_models() -> list[dict]

Get available language models.

Returns:

  • list[dict]: List of language model configurations

Example:

models = client.list_language_models()
for model in models:
    print(f"Name: {model['name']}")
    print(f"Provider: {model['provider']}")
    print(f"Capabilities: {model.get('capabilities', [])}")
    print(f"Max tokens: {model.get('max_tokens', 'Unlimited')}")
    print()

🏥 Health & Status

Ping

ping() -> bool

Check if the API is accessible.

Returns:

  • bool: True if accessible, False otherwise

Example:

if client.ping():
    print("✅ API is accessible")
else:
    print("❌ API is not accessible")

🔄 Backward Compatibility

Alias Methods

The following methods are aliases for backward compatibility:

  • get_agent(agent_id) → get_agent_by_id(agent_id)

  • get_tool(tool_id) → get_tool_by_id(tool_id)

  • get_mcp(mcp_id) → get_mcp_by_id(mcp_id)

📊 Data Models

Agent Model

class Agent(BaseModel):
    id: str                    # Unique identifier
    name: str                  # Human-readable name
    instruction: str | None    # System prompt
    description: str | None    # Optional description
    type: str | None          # Agent type
    framework: str | None     # Framework used
    version: str | None       # Version string
    tools: list[dict] | None  # Associated tools
    agents: list[dict] | None # Associated agents
    agent_config: dict | None # Configuration
    timeout: int = 300        # Timeout in seconds

Methods:

  • run(message: str, **kwargs) -> str: Run the agent

  • update(**kwargs) -> Agent: Update agent attributes

  • delete() -> None: Delete the agent

Tool Model

class Tool(BaseModel):
    id: str                    # Unique identifier
    name: str                  # Tool name
    tool_type: str | None     # Tool type
    description: str | None    # Tool description
    framework: str | None     # Framework used
    version: str | None       # Version string
    tool_script: str | None   # Script content
    tool_file: str | None     # File path

Methods:

  • get_script() -> str: Get tool script content

  • update(**kwargs) -> Tool: Update tool attributes

  • delete() -> None: Delete the tool

MCP Model

class MCP(BaseModel):
    id: str                    # Unique identifier
    name: str                  # MCP name
    description: str | None    # MCP description
    config: dict | None       # Configuration
    framework: str | None     # Framework used
    version: str | None       # Version string
    transport: str | None     # Transport type
    authentication: dict | None # Auth config
    metadata: dict | None     # Additional metadata

Methods:

  • get_tools() -> list[dict]: Get available tools

  • update(**kwargs) -> MCP: Update MCP attributes

  • delete() -> None: Delete the MCP

🚨 Error Handling

Common Error Patterns

import httpx

try:
    response = client.run_agent("agent-123", "Hello")
except httpx.HTTPStatusError as e:
    if e.response.status_code == 401:
        print("Authentication failed - check your API key")
    elif e.response.status_code == 404:
        print("Resource not found")
    else:
        print(f"HTTP error: {e}")
except httpx.ConnectError as e:
    print(f"Connection error: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")

📝 Examples

Complete Workflow

from glaip_sdk import Client

# Initialize client
client = Client()

try:
    # Create a tool
    tool = client.create_tool(
        name="calculator",
        file_path="calculator_tool.py",
        description="Basic math operations"
    )
    
    # Create an agent with the tool
    agent = client.create_agent(
        name="math-assistant",
        instruction="You are a math tutor. Use tools to solve problems.",
        tools=[tool]
    )
    
    # Run the agent
    response = agent.run("What is 15 * 23?")
    print(response)
    
    # Clean up
    agent.delete()
    tool.delete()
    
except Exception as e:
    print(f"Error: {e}")

Batch Processing

from glaip_sdk import Client

client = Client()

# Create multiple agents
agents = []
for i in range(3):
    agent = client.create_agent(
        name=f"worker-{i}",
        instruction=f"You are worker agent {i}. Process tasks efficiently."
    )
    agents.append(agent)

# Process tasks
tasks = ["Task A", "Task B", "Task C"]
results = []

for agent, task in zip(agents, tasks):
    try:
        response = agent.run(f"Process: {task}")
        results.append(response)
    except Exception as e:
        print(f"Error processing {task}: {e}")

# Clean up
for agent in agents:
    agent.delete()

print(f"Processed {len(results)} tasks successfully")

🔗 Navigation

← Back to Reference

This API reference is generated from the actual SDK code and kept up-to-date automatically.

PreviousReferenceNextCLI Commands