Editing Agents with Agents
This skill teaches you how to edit existing Lucid agents via the API.
When to Use
Use this skill when you need to:
-
Update an existing agent's configuration
-
Enable or disable an agent
-
Modify entrypoints (add, remove, update)
-
Change agent metadata or description
-
Update payment configuration
Three Options for Editing Agents
Option 1: MCP Tool with Server Wallet (SIWE)
Use the MCP tool with Sign In With Ethereum (SIWE) and your server wallet:
First, ensure you're authenticated via SIWE in your MCP client
Your server wallet will be used for authentication
Then use the MCP tool to edit an agent
edit_lucid_agent({ agentId: "ag_abc123", enabled: false, description: "Updated via MCP" })
The MCP tool handles:
-
SIWE authentication with your server wallet
-
x402 payment signature generation
-
API request with PAYMENT-SIGNATURE header
Option 2: SDK as Signer (Your Own Wallet)
Use the Lucid Agents SDK with your own wallet:
import { createX402Payment } from '@lucid-agents/payments'; import { privateKeyToAccount } from 'viem/accounts'; import { baseSepolia } from 'viem/chains';
// Setup your wallet
const account = privateKeyToAccount(0x${WALLET_PRIVATE_KEY});
const agentId = 'ag_abc123';
// SDK creates x402 payment signature
const payment = await createX402Payment({
account,
chain: baseSepolia,
resource: {
url: https://api.daydreams.systems/api/agents/${agentId},
description: 'Agent update',
mimeType: 'application/json',
},
amount: '0', // Free for auth
asset: '0x036CbD53842c5426634e7929541eC2318f3dCF7e', // USDC
payTo: account.address,
});
// Update agent
const response = await fetch(https://api.daydreams.systems/api/agents/${agentId}, {
method: 'PUT',
headers: {
'Content-Type': 'application/json',
'PAYMENT-SIGNATURE': btoa(JSON.stringify(payment)),
},
body: JSON.stringify({
enabled: false,
description: 'Updated via SDK',
}),
});
const agent = await response.json();
Option 3: Viem with Custom Signing
Write your own signing logic using viem directly:
How it works:
-
Create an EIP-712 signature with your wallet
-
Include the signature in the PAYMENT-SIGNATURE header
-
The backend extracts the wallet address and verifies ownership
Example:
import { createWalletClient, http } from 'viem'; import { privateKeyToAccount } from 'viem/accounts'; import { baseSepolia } from 'viem/chains'; import { randomBytes } from 'crypto';
const account = privateKeyToAccount(0x${WALLET_PRIVATE_KEY});
const walletClient = createWalletClient({
account,
chain: baseSepolia,
transport: http(),
});
// Create authorization signature const nonce = '0x' + randomBytes(32).toString('hex'); const now = Math.floor(Date.now() / 1000);
const authorization = { from: account.address, to: account.address, value: '0', validAfter: String(now - 600), validBefore: String(now + 300), nonce, };
const signature = await walletClient.signTypedData({ account, domain: { name: 'USDC', version: '2', chainId: 84532, verifyingContract: '0x036CbD53842c5426634e7929541eC2318f3dCF7e', }, types: { TransferWithAuthorization: [ { name: 'from', type: 'address' }, { name: 'to', type: 'address' }, { name: 'value', type: 'uint256' }, { name: 'validAfter', type: 'uint256' }, { name: 'validBefore', type: 'uint256' }, { name: 'nonce', type: 'bytes32' }, ], }, primaryType: 'TransferWithAuthorization', message: authorization, });
// Create payment payload
const paymentPayload = {
x402Version: 2,
resource: {
url: ${BASE_URL}/api/agents/${agentId},
description: 'Agent update',
mimeType: 'application/json',
},
accepted: {
scheme: 'exact',
network: 'eip155:84532',
amount: '0',
asset: '0x036CbD53842c5426634e7929541eC2318f3dCF7e',
payTo: account.address,
maxTimeoutSeconds: 300,
extra: {},
},
payload: {
authorization,
signature,
},
};
// Update agent
const response = await fetch(${BASE_URL}/api/agents/${agentId}, {
method: 'PUT',
headers: {
'Content-Type': 'application/json',
'PAYMENT-SIGNATURE': btoa(JSON.stringify(paymentPayload)),
},
body: JSON.stringify({
enabled: false,
description: 'Updated via wallet auth',
}),
});
- Session Authentication (Cookie)
Use this when:
-
The user is logged in via Better Auth
-
You have a session cookie from the browser
-
The agent was created by a logged-in user
Example:
const response = await fetch(${BASE_URL}/api/agents/${agentId}, {
method: 'PUT',
headers: {
'Content-Type': 'application/json',
'Cookie': sessionCookie,
},
body: JSON.stringify({
enabled: false,
}),
});
What Can Be Updated
Allowed Fields
You can update the following fields on an existing agent:
-
enabled (boolean): Enable or disable the agent
-
name (string): Human-readable name (1-128 chars)
-
description (string): Description (max 1024 chars)
-
entrypoints (array): Full entrypoints array (replaces existing)
-
paymentsConfig (object): Payment configuration
-
walletsConfig (object): Wallet configuration
-
a2aConfig (object): Agent-to-agent configuration
-
ap2Config (object): Access policy configuration
-
analyticsConfig (object): Analytics configuration
-
identityConfig (object): Identity configuration
-
metadata (object): Custom metadata
Restricted Fields
The following fields cannot be changed after creation:
-
slug : Immutable identifier (tied to setup payment)
-
ownerId : Owner cannot be transferred
-
version : Automatically managed by backend
-
createdAt : Timestamp of creation
Common Operations
Disable an Agent
await fetch(${BASE_URL}/api/agents/${agentId}, {
method: 'PUT',
headers: {
'Content-Type': 'application/json',
'PAYMENT-SIGNATURE': btoa(JSON.stringify(paymentPayload)),
},
body: JSON.stringify({
enabled: false,
}),
});
Update Description
await fetch(${BASE_URL}/api/agents/${agentId}, {
method: 'PUT',
headers: {
'Content-Type': 'application/json',
'PAYMENT-SIGNATURE': btoa(JSON.stringify(paymentPayload)),
},
body: JSON.stringify({
description: 'Updated description',
}),
});
Add a New Entrypoint
// First, get the current agent to retrieve existing entrypoints
const agent = await fetch(${BASE_URL}/api/agents/${agentId}).then(r => r.json());
// Add new entrypoint to existing ones const updatedEntrypoints = [ ...agent.entrypoints, { key: 'new-endpoint', description: 'New endpoint', handlerType: 'js', handlerConfig: { code: 'return { result: input };', }, }, ];
// Update agent with new entrypoints array
await fetch(${BASE_URL}/api/agents/${agentId}, {
method: 'PUT',
headers: {
'Content-Type': 'application/json',
'PAYMENT-SIGNATURE': btoa(JSON.stringify(paymentPayload)),
},
body: JSON.stringify({
entrypoints: updatedEntrypoints,
}),
});
Update Entrypoint Price
// Get current agent
const agent = await fetch(${BASE_URL}/api/agents/${agentId}).then(r => r.json());
// Update price on specific entrypoint const updatedEntrypoints = agent.entrypoints.map(ep => { if (ep.key === 'chat') { return { ...ep, price: '20000' }; // Update to 0.02 USDC } return ep; });
// Update agent
await fetch(${BASE_URL}/api/agents/${agentId}, {
method: 'PUT',
headers: {
'Content-Type': 'application/json',
'PAYMENT-SIGNATURE': btoa(JSON.stringify(paymentPayload)),
},
body: JSON.stringify({
entrypoints: updatedEntrypoints,
}),
});
Enable Analytics
await fetch(${BASE_URL}/api/agents/${agentId}, {
method: 'PUT',
headers: {
'Content-Type': 'application/json',
'PAYMENT-SIGNATURE': btoa(JSON.stringify(paymentPayload)),
},
body: JSON.stringify({
analyticsConfig: {
enabled: true,
},
}),
});
Ownership and Permissions
Who Can Edit an Agent?
Only the owner of an agent can edit it. Ownership is determined by:
-
Wallet-created agents: Owned by the user account associated with the wallet address
-
Session-created agents: Owned by the logged-in user who created it
Ownership Verification
The backend automatically:
-
Extracts the user identity from authentication (wallet or session)
-
Loads the agent from the database
-
Verifies agent.ownerId matches the authenticated user's ID
-
Rejects the request with 403 if ownership doesn't match
Error Handling
Common errors when editing agents:
401 Unauthorized
{ "error": "Unauthorized", "code": "UNAUTHORIZED", "message": "Authentication required - provide PAYMENT-SIGNATURE header or valid session" }
Solution: Include valid authentication (PAYMENT-SIGNATURE or session cookie)
403 Forbidden
{ "error": "Forbidden", "code": "FORBIDDEN", "message": "You do not have permission to edit this agent" }
Solution: Ensure you're authenticated as the agent owner
404 Not Found
{ "error": "Agent not found", "code": "AGENT_NOT_FOUND" }
Solution: Verify the agent ID is correct
400 Validation Error
{ "error": "Validation failed", "details": {...} }
Solution: Check that all fields match the expected schema
409 Slug Conflict
{ "error": "Cannot change agent slug", "code": "SLUG_IMMUTABLE" }
Solution: Remove the slug field from your update - slugs cannot be changed
API Endpoint
PUT /api/agents/:agentId
Request Headers:
-
Content-Type: application/json
-
PAYMENT-SIGNATURE: <base64-encoded-payment-payload> (for wallet auth)
-
Cookie: <session-cookie> (for session auth)
Request Body:
{ "enabled": false, "description": "Updated description", "entrypoints": [...], "analyticsConfig": {...} }
Response:
-
200 OK: Agent updated successfully, returns updated agent object
-
401 Unauthorized: Authentication required
-
403 Forbidden: User doesn't own the agent
-
404 Not Found: Agent doesn't exist
-
400 Bad Request: Validation error
Complete Example Script
See scripts/edit-agent-with-payment-auth.ts for a complete working example of editing an agent with wallet authentication.
Related Skills
-
hono-runtime-api: Complete API reference for all operations
-
lucid-agent-creator: Creating new agents