ogpu.agent

High-level wrappers for the agent scheduler role. An agent is an address authorized via Terminal.setAgent(agent, True) by a master or client — once authorized, the agent's own key can sign Nexus operations on the principal's behalf. The protocol checks isAgentOf(principal, msg.sender) to authorize each call.

The typical use case is a scheduler service: a single long-running process (e.g. The Order, OpenGPU's built-in scheduler at 0x306Dc3fF30254675B209D916475094401aCC4a1E) that watches for new tasks and dispatches them to providers managed by a given master — without the master ever having to sign each transaction.

Every function reads AGENT_PRIVATE_KEY from the environment when private_key is omitted. See the agents guide for the full end-to-end flow including how to set up the agent on the master side first.

Scheduler role, not response producer

submit_response is not exposed here, and not anywhere else in the SDK either. Agents schedule work (register / attempt / unregister) — they do not produce response content. Response payloads come from a real compute run (the docker source executing its handler) and must be signed by the provider whose image produced them, otherwise providers could spoof responses from arbitrary scripts.

No setBaseData / setLiveData

Provider self-reported state writes use msg.sender and must come from the provider's own runtime. Like submit_response, they're not in ogpu.agent and not in ogpu.protocol.terminal either — self-reported state from random SDK callers would defeat the point of the field.

---

ogpu.agent.register_to

register_to(source: str, provider: str, env: int, private_key: str | None = None, **_ignored: Any) -> Receipt

Register a provider to a source on behalf of the authorizing principal.

Calls Nexus.register signed by the agent's key. The protocol authorizes the call via its isAgentOf check against the master (or client) that authorized this agent via Terminal.setAgent.

Parameters:

Name	Type	Description	Default
source	str	Source contract address to register to.	required
provider	str	Provider address being registered. Must be a provider managed by the principal that authorized the agent.	required
env	int	Preferred environment bitmask (Environment.CPU.value = 1, NVIDIA = 2, AMD = 4).	required
private_key	str | None	Agent signer. Falls back to AGENT_PRIVATE_KEY environment variable.	None

Returns:

Type	Description
Receipt	Receipt for the registration.

Raises:

Type	Description
InsufficientLockupError	Provider doesn't hold enough lockup.
SourceInactiveError	Source is inactivated.
MissingSignerError	If no signer is available.

ogpu.agent.unregister_from

unregister_from(source: str, provider: str, private_key: str | None = None, **_ignored: Any) -> Receipt

Unregister a provider from a source on behalf of the authorizing principal.

Calls Nexus.unregister signed by the agent's key.

Parameters:

Name	Type	Description	Default
source	str	Source contract address.	required
provider	str	Provider address to unregister.	required
private_key	str | None	Agent signer. Falls back to AGENT_PRIVATE_KEY.	None

Returns:

Type	Description
Receipt	Receipt for the unregistration.

ogpu.agent.attempt

attempt(task: str, provider: str, suggested_payment: int, private_key: str | None = None, **_ignored: Any) -> Receipt

Submit an attempt on behalf of a provider, signed by the agent's key.

Calls Nexus.attempt — records that the provider is working on the task, sets the task status to ATTEMPTED on first call, and commits the provider to eventually produce a response.

The agent signs, but the provider argument is the address the attempt is attributed to on-chain — the agent is a scheduler, not an attempter.

Parameters:

Name	Type	Description	Default
task	str	Task contract address.	required
provider	str	Provider the attempt is attributed to.	required
suggested_payment	int	Advisory payment the provider expects from the client's escrowed payment, in wei.	required
private_key	str | None	Agent signer. Falls back to AGENT_PRIVATE_KEY.	None

Returns:

Type	Description
Receipt	Receipt for the attempt.

Raises:

Type	Description
TaskExpiredError	Task has passed its expiryTime.
TaskAlreadyFinalizedError	Task is in terminal state.