Overview
Lifecycle methods manage the agent’s operational state. An agent transitions through several states from creation to deactivation. All methods in this section are called on an Agent instance.
State Diagram
The agent follows this state machine during its lifecycle:
The AgentStatus enum maps to these states:
enum AgentStatus {
UNKNOWN = 'unknown',
ACTIVATING = 'activating',
ACTIVATION_FAILED = 'activation_failed',
ACTIVATED = 'activated',
RUNNING = 'running',
RUN_FAILED = 'run_failed',
BLOCKED = 'blocked',
DEACTIVATING = 'deactivating',
DEACTIVATION_FAILED = 'deactivation_failed',
DEACTIVATED = 'deactivated',
EMERGENCY = 'emergency',
DEACTIVATED_FEE_NOT_PAID = 'deactivated_fee_not_paid',
BRIDGING = 'bridging',
}
activate(options)
async activate(options: ActivateOptions): Promise<ActivateResponse>
Parameters
The EOA address that owns the smart account.
The deposit token address (e.g., USDC).
List of protocol names the agent should allocate to. Must contain at least one protocol.
The transaction hash of the user’s deposit into the smart account.
Optional allocation constraints (min/max amounts per protocol, excluded protocols).
Return Type
interface ActivateResponse {
message: string;
wallet: string;
}
Example
import { Giza, Chain } from '@gizatech/agent-sdk';
const giza = new Giza({ chain: Chain.BASE });
const agent = await giza.createAgent('0xUserEOA...');
const result = await agent.activate({
owner: '0xUserEOA...',
token: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', // USDC on Base
protocols: ['aave', 'compound', 'moonwell'],
txHash: '0xDepositTransactionHash...',
});
console.log(result.message); // 'Agent activated successfully'
console.log(result.wallet); // smart account address
Activation with Constraints
await agent.activate({
owner: '0xUserEOA...',
token: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
protocols: ['aave', 'compound', 'moonwell'],
txHash: '0xDepositTxHash...',
constraints: [
{
kind: 'max_allocation_amount_per_protocol',
params: { protocol: 'aave', amount: '500000000' },
},
{
kind: 'exclude_protocol',
params: { protocol: 'euler' },
},
],
});
deactivate(options?)
async deactivate(options?: DeactivateOptions): Promise<DeactivateResponse>
Parameters
Whether to transfer funds back to the owner’s EOA. Defaults to true.
Return Type
interface DeactivateResponse {
message: string;
}
Example
// Deactivate and transfer funds back (default)
const result = await agent.deactivate();
console.log(result.message);
// Deactivate but keep funds in the smart account
const result2 = await agent.deactivate({ transfer: false });
Deactivation is asynchronous. The agent enters the DEACTIVATING state and may take time to withdraw from all protocols. Use agent.waitForDeactivation() to poll until the process completes.
topUp(txHash)
async topUp(txHash: string): Promise<TopUpResponse>
Parameters
The transaction hash of the additional deposit.
Return Type
interface TopUpResponse {
message: string;
}
Example
const result = await agent.topUp('0xAdditionalDepositTxHash...');
console.log(result.message);
The agent must be in the ACTIVATED state to accept a top-up. If the agent is deactivating or deactivated, the call will fail.
run()
async run(): Promise<RunResponse>
Return Type
interface RunResponse {
status: string;
}
Example
const result = await agent.run();
console.log('Run status:', result.status);
Agents also run automatically on a schedule. Use run() when you want to trigger an immediate rebalancing, for example after market conditions change.
Complete Lifecycle Example
import { Giza, Chain } from '@gizatech/agent-sdk';
const giza = new Giza({ chain: Chain.BASE });
const USDC = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';
// 1. Create agent
const agent = await giza.createAgent('0xUserEOA...');
// 2. Activate after user deposits
await agent.activate({
owner: '0xUserEOA...',
token: USDC,
protocols: ['aave', 'compound'],
txHash: '0xInitialDepositTx...',
});
// 3. Top up with additional deposit
await agent.topUp('0xSecondDepositTx...');
// 4. Trigger a manual run
await agent.run();
// 5. Monitor status
const info = await agent.portfolio();
console.log('Status:', info.status);
// 6. Deactivate when done
await agent.deactivate();
// 7. Wait for deactivation to complete
const final = await agent.waitForDeactivation({
interval: 10000, // poll every 10 seconds
timeout: 300000, // give up after 5 minutes
onUpdate: (status) => console.log('Status:', status),
});
console.log('Final status:', final.status);
Next Steps
