Agent Usage

An Agent is an extension of a GizaModel, it offers the same capabillities with extra functionalities like, account and contracts handling.

The agent needs the following data to work:

• id: model identifier.

• version_id: version identifier.

• chain: chain where the smart contracts are deployed, to check what chains are available you can run `ape networks list`.

• contracts: this is the definition of the contracts as a dictionary, more here.

• account: this is an optional field indicating the account to use, if it is not provided we will use the account specified at creation but otherwise we will use the specified one if it exists locally.

from giza.agents import GizaAgent

agent = GizaAgent(
        contracts=<contracts-dict>,
        id=<model-id>,
        version_id=<version-id>,
        chain=<chain>,
        account=<account>,
    )

There is another way to instantiate an agent using the agent-id received on the creation request with the CLI:

from giza.agents import GizaAgent

agent = GizaAgent.from_id(
    id=<agent-id>,
    contracts=<contracts-dict>,
    chain=<chain>,
    account=<account>,
    )

Generate a verifiable prediction

This Agent brings an improved predict function which encapsulates the result in an AgentResult class. This is the class responsible for handling and checking the status of the proof related to the prediction, when the value is accessed, the execution is blocked until the proof is generated and verified. It looks the same as the GizaModel.predict :

result = agent.predict(
    input_feed=<input-data>,
    verifiable=True,
)    

The verifiable argument should be True to force the proof creation, it is kept here for compatibility with GizaModel.

Access the prediction

To access the prediction you can easily do so by using the value property of the result:

result = agent.predict(
    input_feed=<input-data>,
    verifiable=True,
)

# This will access the value, if not verified it waits until verification is done
result.value

Modify polling options

When using the value at AgentResult, there are some default options used when polling for the result of the proof and the maximum timeout for the proof job. The defaults are 600 seconds for timeout and 10 seconds for poll_interval.

result = agent.predict(
    input_feed=<input-data>,
    verifiable=True,
    timeout=<timeout in seconds>,
    poll_interval=<poll interval in seconds>,
)  

Dry Run a prediction

When we are developing the solution is possible that we don't need to wait for the proof to be generated as we are iterating a solution. For this there is a dry_run option which gets the prediction from the verifiable model but does not launch nor wait for the proof to be generated, improving development times and developer experience.

result = agent.predict(
    input_feed=<input-data>,
    verifiable=True,
    dry_run=True,
)  

Execute Contracts

The Agent handles the execution and handling of the contracts that have been specified in the contracts attribute. Under the hood, the agent gets the information about the contract and allows for the execution of the contract in an easy way.

These contracts must be executed inside the execute() context, which handles the contract's instantiation as well as the signing of the contracts:

from giza.agents import GizaAgent

contracts_dict = {
    "lp": ...,
}

agent = GizaAgent.from_id(
    id=<agent-id>,
    contracts=<contracts-dict>,
    chain=<chain>,
    account=<account>,
)

result = agent.predict(
    input_feed=<input-data>,
    verifiable=True,
)

with agent.execute() as contracts:
    contracts.lp.foo(result.value)
    

In the execute the contract is accessed as contracts.lp and executes the function foo of the contract. As it is using the value of the result, the contract function won't be executed until the result is verified or an error will be raised.