client
Class info¶
Classes¶
| Name | Children | Inherits |
|---|---|---|
| McpHttpSession pyt3client.mcp One MCP session against a T3 Code environment's `/mcp`. |
||
| T3Client pyt3client.client Typed client for one T3 Code environment, over its `/mcp` endpoint. |
||
| T3ProtocolError pyt3client.errors The server answered in a shape this client does not understand. |
||
| T3ToolError pyt3client.errors A tool call was refused. |
||
| ThreadWaitInput pyt3client.models.tools |
🛈 DocStrings¶
High-level async client for a T3 Code environment.
MAX_WAIT_CHUNK_SECONDS
module-attribute
¶
MAX_WAIT_CHUNK_SECONDS = 50.0
Longest single t3_thread_wait call wait_for_thread makes.
/mcp sends nothing while a wait is open, and T3 Connect's edge drops idle
requests after about 100 s, so upstream splits forwarded waits into calls of
at most 50 s (see "Peer links" in docs/internals/remote.md upstream).
T3Client
¶
Typed client for one T3 Code environment, over its /mcp endpoint.
Every tool the environment offers is reachable through call, typed by the
ToolSpec constants in pyt3client.models.tools:
from pyt3client import T3Client, pair
from pyt3client.models.tools import THREAD_LAUNCH, ThreadLaunchInput
credentials = await pair("http://127.0.0.1:3773", "PAIRING-CODE")
async with T3Client.from_credentials(credentials) as t3:
launched = await t3.call(
THREAD_LAUNCH,
ThreadLaunchInput(project_id="...", title="Fix tests", message="Fix the tests"),
)
done = await t3.wait_for_thread(launched.thread_id, run_id=launched.run_id)
Get credentials with pyt3client.pair(); T3 Code's server reference for the
tools is docs/orchestration-v2/orchestrator-mcp-server.md upstream.
Source code in src/pyt3client/client.py
43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 | |
server_info
property
¶
server_info: dict[str, JsonValue] | None
serverInfo from the MCP handshake, once a request has been made.
__init__
¶
__init__(
base_url: str,
token: str | SecretStr,
*,
mode_limit: tuple[RuntimeMode, InteractionMode] | None = None,
client_name: str = "pyt3client",
timeout: float = 60.0,
http_client: AsyncClient | None = None
) -> None
Create a client; the MCP session opens on first use.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
base_url
|
str
|
Environment origin, such as |
required |
token
|
str | SecretStr
|
MCP bearer token, as returned by |
required |
mode_limit
|
tuple[RuntimeMode, InteractionMode] | None
|
Narrow this client below its approved level for every call:
threads it starts or steers run with at most this runtime and
interaction mode. Sent as the |
None
|
client_name
|
str
|
Name reported in the MCP |
'pyt3client'
|
timeout
|
float
|
Default HTTP timeout in seconds. |
60.0
|
http_client
|
AsyncClient | None
|
Client to use; created and owned by this instance otherwise. |
None
|
Source code in src/pyt3client/client.py
66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 | |
aclose
async
¶
aclose() -> None
End the MCP session and close the HTTP client if this instance owns it.
Source code in src/pyt3client/client.py
143 144 145 146 147 | |
call
async
¶
call(
tool: ToolSpec[InputT, OutputT], params: InputT | None = None, *, timeout: float | None = None
) -> OutputT
Call a tool with typed arguments and return its typed result.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
tool
|
ToolSpec[InputT, OutputT]
|
The tool, such as |
required |
params
|
InputT | None
|
Its arguments; |
None
|
timeout
|
float | None
|
HTTP read timeout in seconds for this call. |
None
|
Raises:
| Type | Description |
|---|---|
T3ToolError
|
The tool refused, such as |
T3McpError
|
The request was rejected, such as invalid arguments. |
T3ProtocolError
|
The result does not match the generated model. |
Source code in src/pyt3client/client.py
166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 | |
call_raw
async
¶
call_raw(
name: str, arguments: Mapping[str, JsonValue] | None = None, *, timeout: float | None = None
) -> JsonValue
Call any tool by name with untyped arguments; for tools newer than the models.
Raises:
| Type | Description |
|---|---|
T3ToolError
|
The tool refused. |
T3McpError
|
The request was rejected. |
Source code in src/pyt3client/client.py
200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 | |
descriptor
async
¶
descriptor() -> EnvironmentDescriptor
The environment's public descriptor (id, version, capability flags).
Source code in src/pyt3client/client.py
154 155 156 | |
from_credentials
classmethod
¶
from_credentials(
credentials: T3Credentials,
*,
mode_limit: tuple[RuntimeMode, InteractionMode] | None = None,
client_name: str = "pyt3client",
timeout: float = 60.0,
http_client: AsyncClient | None = None
) -> Self
Create a client from the result of pair().
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
credentials
|
T3Credentials
|
Credentials from |
required |
mode_limit
|
tuple[RuntimeMode, InteractionMode] | None
|
See |
None
|
client_name
|
str
|
See |
'pyt3client'
|
timeout
|
float
|
See |
60.0
|
http_client
|
AsyncClient | None
|
See |
None
|
Source code in src/pyt3client/client.py
104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 | |
list_tools
async
¶
list_tools() -> list[ToolInfo]
Tools the server offers this credential, with their JSON Schemas.
Useful to detect drift against the generated models: a newer server
may offer tools pyt3client.models.tools does not know yet.
Source code in src/pyt3client/client.py
158 159 160 161 162 163 164 | |
wait_for_thread
async
¶
wait_for_thread(
thread_id: str,
*,
run_id: str | None = None,
timeout: float | None = None,
until_delegated_work_settled: bool = False,
environment_id: str | None = None
) -> ThreadWaitOutput
Wait until a thread's run ends, for longer than one HTTP request may stay idle.
Repeats t3_thread_wait in chunks of at most MAX_WAIT_CHUNK_SECONDS.
A run ends as completed, failed, cancelled, interrupted or
rolled_back; an idle thread returns at once. Timing out does not stop
the run: the result then has timed_out=True and the latest status.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
thread_id
|
str
|
Thread to wait on. |
required |
run_id
|
str | None
|
Run to wait for. Without it the server pins the thread's latest run on the first call, and later chunks keep waiting on that run. |
None
|
timeout
|
float | None
|
Overall limit in seconds; waits until the run ends otherwise. |
None
|
until_delegated_work_settled
|
bool
|
Also wait for the run's subagents and
background tasks; |
False
|
environment_id
|
str | None
|
Linked environment the thread lives in, if not this one. |
None
|
Source code in src/pyt3client/client.py
216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 | |