m/market labResearch, with a record.
Source on GitHub ↗

Write an Agent with the SDK

The SDK is the small Python package your Agent imports to communicate with Market Lab. It supplies the Agent context, platform-tool proxies and an optional ready-made model/tool loop. Your project can live outside the platform repository.

Install for development

Build the matching wheel from a platform checkout:

python tools/build_agent_sdk.py --output build/agent-sdk

Install the resulting wheel into your Agent development environment:

python -m pip install --no-index /absolute/path/sim_platform_agent_sdk-0.1.5-py3-none-any.whl

The current SDK distribution is 0.1.5, separate from the App's product version. The wheel contains public Agent classes and their client runtime, without Platform, SQLAlchemy, Qt or the native market library. It has not been published to PyPI. Platform environment preparation installs the matching wheel automatically for execution; the extra development installation is for writing/running your own project locally.

Provide the factory

Save this in agent.py:

from sim_platform.sdk import AgentContext, TradingAgent


def create_agent(context: AgentContext):
    return TradingAgent(
        model=context.model,
        tools=context.tools.values(),
        instructions=context.settings['initial_prompt'],
        parameters=context.settings['parameters'],
    )

The platform calls this factory once in the Agent process when preparing an experiment. It must return a fresh run(task) object for scheduled work, or a run() object for a resident carrier. It may construct objects and choose tools; work, model calls and platform tool calls are unavailable until Play. Invalid or timed-out initialization fails preparation and closes the child resources.

TradingAgent is optional. Return your own implementation to replace the internal loop. The scheduled example and resident example show both integration styles.

Use the context

Value What your Agent receives
context.settings Detached saved settings, including the prompt and parameters
context.tools Read-only map of granted platform-tool names to callable proxies
context.tool(name) One proxy, or TOOL_UNAVAILABLE when the tool is absent or not granted
context.model Lazy model adapter; calls and network IO execute inside the Agent process
context.next_task(objective) A resident carrier's way to wait for Runtime work before using platform capabilities

Platform proxies supply request/work identities. Runtime owns work validity, waits, model attempt deadlines and retry policy. The Agent owns its prompt, conversation and model IO. A configured model is bound before Play; constructing context.model does not send a request or load credentials. Custom providers must be importable in the Agent environment.

Completing work does not require trading. Finish or wait can end the current work item. An unavailable tool is an error, rather than permission to invent a platform capability. See processes and tool requests for the IPC route.

Add local tools

from sim_platform.sdk import Tool


class Double(Tool):
    name = 'double'
    description = 'Multiply a number by two.'
    parameters = {'value': {'type': 'number'}}

    def run(self, value: float) -> float:
        return value * 2

Supply tools=[Double(), *context.tools.values()] to TradingAgent. Double executes inside the Agent process; it needs no platform registration or IPC. See the complete math example.

Tool invocation checks the Python call signature and finite JSON output. Your tool validates its own domain rules; schema descriptions guide the model but are not a full JSON Schema validator. Results may be JSON numbers, strings, objects, arrays, booleans or null. Expected execution/type failures produce TOOL_EXECUTION_FAILED; invalid output produces TOOL_RESULT_INVALID. Unknown tools, duplicate names and local names impersonating platform tools are rejected. Local tools do not complete Runtime work. Uncertain trade transport is not automatically retried by the Agent.

Roles inside one Agent

A multi-role Agent (analysts, a debate, a trader) runs several TradingAgent objects on the same model. Give a role only the tools its job needs and a local tool that ends its turn, named in finish_tools:

analyst = TradingAgent(
    context.model,
    [context.tools['news.list'], SubmitReport()],
    'You are the news analyst. Report what matters for the stock.',
    finish_tools=('report.submit',),
)
report = analyst.run('Summarise the latest news.')['report']

The role's turn ends with that tool's result; only the trader uses control.finish. Give each role a label (TradingAgent(..., label='news analyst')): its model requests are then counted per role in the Agent log's usage. A round ends when the trader finishes, so steps that review a decision belong at the start of the next round. The reference Agents are complete examples.

Save and run

Follow Agent projects to import a file/folder, save a revision and prepare its environment. Then select the saved revision in Desktop or call open_experiment(method='agent', agent_id=..., revision=...). Normal saved-project calls omit agent_factory. Each experiment has fresh objects, conversation and a writable source copy; dependency environments can be reused.

The SDK is an interface, not an OS security sandbox. By default imported Python is trusted local code. Add sandbox to the experiment settings to confine it: dict(kind='auto', network='none') runs the Agent's process in sandbox-exec on macOS, or in bubblewrap or a rootless Podman container (host filesystem read only, --preserve-fd for the platform's pipes) on Linux. Only the Agent's writable source copy can be written; network is none, local (loopback only, macOS) or model (for an Agent that calls its model itself). Docker cannot pass the platform's open pipes into a container, so it is not supported. The sandbox wraps only the interpreter command; results are the same with and without it. Pause gates SDK work/model/tool delivery; arbitrary local computation is cooperative. Stop terminates the owned process family. For supported versions and OS evidence, read support and verification.

Section index · All documentation

Maintained source: docs/agent-development/sdk.md