Migration Guides

Step-by-step guides for migrating between isA API versions.

API Versioning Strategy

isA uses path-based versioning (/api/v1/, /api/v2/). When breaking changes are introduced:

• The old version continues to work for a deprecation period (minimum 6 months)
• Migration guides are published here
• The changelog notes the deprecation timeline

Chat API: Legacy Format to Structured Format

What Changed

The inference endpoint now supports tools, response_format, and stream as first-class parameters instead of embedding them in input_data.

Before (Legacy)

import requests
 
response = requests.post("https://api.isagent.io/api/v1/invoke", json={
    "input_data": [
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello"},
    ],
    "task": "chat",
    "service_type": "text",
    "model": "gpt-4o",
    "provider": "openai",
    "stream": False,
    "temperature": 0.7,
    "max_tokens": 4096,
})

After (New Format)

import requests
 
response = requests.post("https://api.isagent.io/api/v1/chat/completions", json={
    "model": "gpt-4o",
    "messages": [
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello"},
    ],
    "temperature": 0.7,
    "max_tokens": 4096,
    "tools": [
        {"type": "web_search", "web_search": {"max_results": 5}}
    ],
    "response_format": {
        "type": "json_schema",
        "json_schema": {"name": "response", "schema": {"type": "object"}}
    },
})

Migration Steps

1. Change endpoint from /api/v1/invoke to /api/v1/chat/completions
2. Rename input_data to messages
3. Remove task, service_type, provider (auto-detected from model ID)
4. Add tools array for built-in tools (web_search, file_search)
5. Use response_format for structured outputs instead of responseFormat: "json"

Compatibility

The unified /api/v1/invoke endpoint remains supported and is the preferred endpoint when you need isA-specific routing fields such as provider, service_type, or task.

Agent Config: v1 to v2

What Changed

Agent configurations gained execution_profiles for A2A deployment and routing_hints for dynamic routing.

Before

{
  "name": "support-bot",
  "model": "gpt-4o",
  "system_prompt": "You are a support agent.",
  "mode": "REACTIVE",
  "tools": ["search_kb", "create_ticket"]
}

After

{
  "name": "support-bot",
  "model": "gpt-4o",
  "system_prompt": "You are a support agent.",
  "mode": "REACTIVE",
  "tools": ["search_kb", "create_ticket"],
  "execution_profiles": {
    "default": {
      "environment": "cloud_pool",
      "max_turns": 10,
      "timeout_seconds": 300
    }
  },
  "routing_hints": {
    "domains": ["support", "billing"],
    "priority": 1
  }
}

Migration Steps

1. Add execution_profiles.default with your preferred environment
2. Optionally add routing_hints for multi-agent routing
3. Existing configs without these fields continue to work with defaults

Authentication: Token Format Update

What Changed

API keys now use the isa_ prefix for identification. Existing keys without the prefix continue to work.

Before

curl -H "Authorization: Bearer sk_abc123..." https://api.isagent.io/api/v1/models

After

curl -H "Authorization: Bearer isa_abc123..." https://api.isagent.io/api/v1/models

Migration Steps

1. Generate new API keys in the Console (they auto-get the isa_ prefix)
2. Update your environment variables with the new key
3. Old keys continue to work — no hard cutoff

MCP: Direct REST Calls to the Agent SDK Transport

What Changed

The supported hosted Agent SDK path uses the MCP streamable-HTTP transport at POST /mcp. Configure the base URL and let the SDK construct the transport path. Do not derive or publish versioned REST routes for api.isagent.io.

Supported Agent SDK Path

export ISA_MCP_URL=https://api.isagent.io
export ISA_MCP_API_KEY='isa_...'

from isa_agent_sdk import execute_tool
 
result = await execute_tool(
    tool_name="web_search",
    tool_args={"query": "isA platform"},
)
 
if result.tool_error:
    raise RuntimeError(result.tool_error)
print(result.tool_result_value)

The SDK removes a trailing /mcp from ISA_MCP_URL when necessary and sends the protocol request to POST /mcp. ISA_MCP_API_KEY is attached only to the active request. MCP_SERVER_URL remains a legacy, lower-priority alias. For identity-scoped tools, pass only the verified principal through execute_tool(user_id=...).

Migration Steps

1. Upgrade isa-agent-sdk to a release containing the hosted MCP fixes.
2. Configure the hosted base URL and a scoped MCP key through the environment.
3. Replace hand-built hosted MCP URLs with execute_tool() calls.
4. Check result.tool_error and retain tool_result_value for diagnostics.

SDK Updates

Python SDK

# Check current version
pip show isa-agent-sdk
 
# Upgrade to latest
pip install --upgrade isa-agent-sdk

TypeScript SDK

# Check current version
npm list @isa/core
 
# Upgrade to latest
npm install @isa/core@latest

Breaking Changes by Version