[Bug] `session.error` with `t.asString is not a function` when using `session.send()` with BYOK provider

[Akhand-99]

## Description

When using the Python SDK with a BYOK provider (tested with Azure OpenAI and Anthropic) and sending a prompt via session.send({"prompt": "..."}), every query results in a session.error event with the message t.asString is not a function. No assistant.message event is ever received — the session silently goes idle.

This makes the SDK completely unusable with BYOK when following the documented session.send() pattern.

## Environment

• SDK version:* github-copilot-sdk==0.2.2
• CLI binary version:* copilot.exe v1.0.21 (bundled)
• Python version:* 3.13
• OS:* Windows 11
• Providers tested:* Azure OpenAI (type: "azure"), Anthropic (type: "anthropic")

## Steps to Reproduce

1. Install the SDK:

pip install github-copilot-sdk==0.2.2

2. Create and run the following script with a valid BYOK provider and API key:

import asyncio

import os

from dotenv import load_dotenv

from copilot import CopilotClient

from copilot.session import PermissionHandler

load_dotenv()

FOUNDRY_MODEL_URL = "https://<your-resource>.openai.azure.com/"

async def main():

client = CopilotClient()

await client.start()

session = await client.create_session(

on_permission_request=PermissionHandler.approve_all,

model="<your-deployment-name>",

provider={

"type": "azure",

"base_url": FOUNDRY_MODEL_URL,

"api_key": os.environ["FOUNDRY_API_KEY"],

},

available_tools=[],

infinite_sessions={"enabled": False},

)

done = asyncio.Event()

def on_event(event):

print(f"Received event: {event.type.value}")

if event.type.value == "assistant.message":

print(event.data.content)

elif event.type.value == "session.error":

print(f"error_type={event.data.error_type!r}  message={event.data.message!r}")

done.set()

elif event.type.value == "session.idle":

done.set()

session.on(on_event)

await session.send({"prompt": "What is 2+2?"})

await done.wait()

await session.disconnect()

await client.stop()

asyncio.run(main())

## Actual Behaviour

The session.error event fires with t.asString is not a function. No assistant.message event is received. The session then goes idle.

Received event: pending_messages.modified

Received event: pending_messages.modified

Received event: session.info

Received event: session.tools_updated

Received event: session.error

error_type='query'  message='t.asString is not a function'

Received event: session.idle

## Expected Behaviour

A session.error event should not be fired. A assistant.message event should be received containing the model's response content.

## Additional Notes

• Verified the BYOK endpoint itself is healthy — a direct HTTP call to the Azure OpenAI API returns a valid 200 response:

{

"choices": [

{

"finish_reason": "stop",

"message": { "content": "2 + 2 equals **4**.", "role": "assistant" }

}

],

"model": "gpt-4o-2024-11-20",

"usage": {

"completion_tokens": 11,

"prompt_tokens": 14,

"total_tokens": 25

}

}

• The error occurs regardless of provider type ("azure", "openai", "anthropic").
• The error occurs regardless of whether available_tools=[] is set.
• The reproduction code was written by following the example in docs/auth/byok.md in this repository.

[github-actions]

Investigation Findings

Thanks for the detailed report! I've investigated this and found the root cause.

Root Cause: Documentation Bug

The error is caused by incorrect Python examples in docs/auth/byok.md (and also docs/features/steering-and-queueing.md).

The documentation shows:

await session.send({"prompt": "What is 2+2?"})

But the Python SDK's CopilotSession.send() method takes a plain string as its first argument — not a dict:

async def send(self, prompt: str, *, attachments=None, mode=None, ...) -> str:

When a dict is passed as prompt, the SDK faithfully sends it over JSON-RPC to the CLI binary as a JSON object under the "prompt" field. The CLI then tries to call .asString() on that value (expecting a string), fails with t.asString is not a function, and surfaces it as a session.error event.

Fix

Use a plain string when calling session.send() in Python:

# ✅ Correct
await session.send("What is 2+2?")

# or, to block until the response arrives:
response = await session.send_and_wait("What is 2+2?")
print(response.data.content)

The dict-based { prompt: "..." } syntax is correct for the Node.js/TypeScript SDK (which takes a MessageOptions object), but Python uses a positional string argument.

Files Affected

The incorrect Python call pattern appears in:

• docs/auth/byok.md (line 52) — the example you followed
• docs/features/steering-and-queueing.md (multiple lines)

Reclassification

This issue is reclassified as documentation because the SDK code itself behaves correctly — it passes whatever is given to it straight through to the CLI. The problem is that the Python code examples in the docs use the Node.js-style API signature instead of the correct Python one. Fixing these examples will prevent the issue from affecting other users.

Generated by Bug Handler for issue #1127 · ● 930.4K · ◷