sim_platform.sdk

Public Python interface for defining Agents and their local tools.

Export create_agent(context) from your own module. Return an object with run(task) for scheduled work, or run() for a resident carrier. Platform owns the experiment and supplies context inside the Agent process; no internal imports are needed.

class sim_platform.sdk.AgentContext(client, model, tools, settings)[source]

Bases: object

Configure an Agent without exposing App objects, database or market readers.

model is a lazy model adapter. tools maps granted platform names to remote Tool objects. Add your own Tool instances to the Agent’s tool list; they run locally and are never added to the platform’s operation registry.

Parameters:
  • client (TaskClient)

  • model (AgentModel)

  • tools (Iterable[PlatformTool])

  • settings (AgentSettings)

property settings: AgentSettings

Return a detached copy of prompt, Agent parameters and granted bounds.

tool(name)[source]

Find a granted platform proxy; unknown or ungranted names fail clearly.

Parameters:

name (str)

Return type:

PlatformTool

next_task(instruction)[source]

Wait for Runtime work; valid only after Play, including for resident Agents.

Parameters:

instruction (str)

Return type:

Task

property stopping: bool
class sim_platform.sdk.ScheduledAgent(*args, **kwargs)[source]

Bases: Protocol

An Agent the platform calls once per scheduled task.

run(task)[source]

Perform one scheduled task; use a platform finish/wait tool to end it.

Parameters:

task (Task)

Return type:

Any

class sim_platform.sdk.ResidentAgent(*args, **kwargs)[source]

Bases: Protocol

An Agent that runs its own loop and asks for tasks itself.

run()[source]

Own the loop, obtaining work with context.next_task() before using capabilities.

Return type:

None

class sim_platform.sdk.TradingAgent(model, tools, instructions, parameters=None, finish_tools=(), label=None)[source]

Bases: object

Run a task using a model and callable Tool objects, retaining this run’s history.

Construct this once for an experiment, then call run(task) for each scheduled task. Tools own their interfaces; the model adapter owns provider formatting. The Agent only performs the model -> tools -> model loop. An ordinary text reply does not finish a task: a successful completion Tool must end it.

label names the role (for example ‘news analyst’); evaluations report model calls and tokens per label. finish_tools names local tools whose call also ends the task, returning that tool’s result. Use it for a role inside a larger Agent, such as an analyst that ends by submitting a report, so the role never needs the platform’s finish or wait.

Parameters:
  • model (AgentModel)

  • tools (Iterable[Tool])

  • instructions (str)

  • parameters (Optional[Dict[str, Any]])

  • finish_tools (Iterable[str])

  • label (Optional[str])

run(task)[source]

Perform a task until finish/wait succeeds, returning that completion result.

Pass a string for a direct task, or Task to include a scheduler notification. Context is retained between calls on this Agent. Each tool result is appended before asking the model again; zero trades is a valid completed task.

Parameters:

task (str | Task)

Return type:

dict

class sim_platform.sdk.Task(instruction, notification=<factory>)[source]

Bases: object

Tell the agent what to do, separately from Runtime’s wake-up bookkeeping.

instruction is the task to perform. notification carries the wake reason and timing/events, not current market data. Work IDs remain on AgentClient.

Parameters:
  • instruction (str)

  • notification (Dict[str, Any])

instruction: str
notification: Dict[str, Any]
class sim_platform.sdk.Tool[source]

Bases: ABC

Keep one tool’s name, description, arguments and callable behavior together.

Subclasses implement a typed run() method. Required arguments come from that signature; optional arguments have Python defaults. Both direct code and model calls use run(). Local tools execute in the Agent process and return finite JSON values. They do not need a platform client or a platform result envelope.

name: str
description: str
parameters: dict = {}
category = 'read'
ends_work = False
classmethod required_arguments()[source]
Return type:

Tuple[str, …]

classmethod optional_arguments()[source]
Return type:

Tuple[str, …]

property function_name: str
input_schema(limits)[source]

Describe this tool’s arguments with the experiment’s granted bounds.

Parameters:

limits (dict)

Return type:

dict

invoke(arguments)[source]

Call run() with model-supplied arguments, rejecting missing or extra fields.

Parameters:

arguments (dict)

Return type:

Any

abstract run(*positional, **arguments)[source]

Execute locally and return a JSON value, such as a number, list or object.

Parameters:
  • positional (Any)

  • arguments (Any)

Return type:

Any

exception sim_platform.sdk.ToolError(code, message)[source]

Bases: ContractError

A tool failure with a stable wire code (for example ‘INVALID_ARGUMENT’).

Raised by tool validation and handlers; tool error responses carry the code.

Parameters:
  • code (str)

  • message (str)

Return type:

None