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:
objectConfigure 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:
- property stopping: bool¶
- class sim_platform.sdk.ScheduledAgent(*args, **kwargs)[source]¶
Bases:
ProtocolAn Agent the platform calls once per scheduled task.
- class sim_platform.sdk.ResidentAgent(*args, **kwargs)[source]¶
Bases:
ProtocolAn Agent that runs its own loop and asks for tasks itself.
- class sim_platform.sdk.TradingAgent(model, tools, instructions, parameters=None, finish_tools=(), label=None)[source]¶
Bases:
objectRun 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.
labelnames the role (for example ‘news analyst’); evaluations report model calls and tokens per label.finish_toolsnames 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:
objectTell 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:
ABCKeep 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¶
- 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
- exception sim_platform.sdk.ToolError(code, message)[source]¶
Bases:
ContractErrorA 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