Skip to content

Commit 5ef5260

Browse files
SipherSipher
committed
Update how-to guides for agent setup; enhance error handling, environment configuration, and improve endpoint structure
1 parent f565ed4 commit 5ef5260

File tree

4 files changed

+202
-74
lines changed

4 files changed

+202
-74
lines changed

‎astro.config.mjs‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -55,10 +55,10 @@ export default defineConfig({
5555
collapsed: false,
5656
items: [
5757
{ label: "Agent Registration", slug: "explanations/builders/agent-registration" },
58-
{ label: "Agent Server", slug: "explanations/builders/agent-server" },
59-
{ label: "Agent Client", slug: "explanations/builders/agent-client" },
6058
{ label: "Agent Editing", slug: "explanations/builders/agent-editing" },
6159
{ label: "Demand Signaling", slug: "explanations/builders/demand-signaling" },
60+
{ label: "Agent Server", slug: "explanations/builders/agent-server" },
61+
{ label: "Agent Client", slug: "explanations/builders/agent-client" },
6262
],
6363
},
6464
{
@@ -88,13 +88,13 @@ export default defineConfig({
8888
collapsed: false,
8989
items: [
9090
{ label: "Register an Agent", slug: "how-to-guides/builders/register-an-agent" },
91-
{ label: "Setup Agent Server", slug: "how-to-guides/builders/setup-agent-server" },
92-
{ label: "Setup Agent Client", slug: "how-to-guides/builders/setup-agent-client" },
9391
{ label: "Edit your Agent", slug: "how-to-guides/builders/edit-your-agent" },
94-
{ label: "Create a Signal", slug: "how-to-guides/builders/create-signal" },
9592
{ label: "Manage Capabilities", slug: "how-to-guides/builders/manage-capabilities" },
93+
{ label: "Create a Signal", slug: "how-to-guides/builders/create-signal" },
9694
// { label: "Manage Permissions", slug: "how-to-guides/builders/manage-permissions" },
9795
// { label: "Delegate Emission Streams", slug: "how-to-guides/builders/delegate-emission-streams" },
96+
{ label: "Setup Agent Server", slug: "how-to-guides/builders/setup-agent-server" },
97+
{ label: "Setup Agent Client", slug: "how-to-guides/builders/setup-agent-client" },
9898
],
9999
},
100100
{

‎src/content/docs/how-to-guides/builders/manage-capabilities.mdx‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -53,13 +53,13 @@ By removing outdated or unused capabilities, you reduce the attack surface and k
5353
Navigate to the **Capability Operations** section.
5454

5555
2. **Connect your Torus Wallet**
56-
Ensure you're connected with the agent account that will own the capability.
56+
Ensure you're <RedText variant="light">connected with the agent account</RedText> that will own the capability.
5757

5858
3. **Select the Capability Prefix and Create your Capability Path**
5959
Your capability will follow this structure:
60-
`agent-name.capability-path.METHOD`
60+
**`agent-name.capability-path.METHOD`**
6161

62-
- The `agent-name` is your registered agent name (pre-filled and uneditable).
62+
- The `agent-name` is your registered agent name _<RedText variant="light">(pre-filled and uneditable)</RedText>_.
6363
- The `capability-path` is the custom route you define (e.g. `tokens`, `profile_data`, etc.).
6464

6565
<Aside type="note">
@@ -94,8 +94,8 @@ By removing outdated or unused capabilities, you reduce the attack surface and k
9494
</Aside>
9595

9696
5. **Review information, Submit and Sign the Transaction**
97-
Review the capability path in the **Full Capability Path** field.
98-
If everything is correct, click <RedText variant="light">**Create Capability**</RedText>.
97+
<RedText variant="light">Review the capability path</RedText> in the **Full Capability Path** field.
98+
If everything is correct, click **Create Capability**.
9999
Open the SubWallet extension and <RedText variant="light">sign the transaction</RedText>.
100100
<ClickableImage src={confirmCapability} alt="Confirm Capability" />
101101

@@ -104,6 +104,6 @@ By removing outdated or unused capabilities, you reduce the attack surface and k
104104
Now you can delegate permissions to it.
105105
</Steps>
106106

107-
### Delete a Capability path
107+
## Delete a Capability path
108108

109109
WIP

‎src/content/docs/how-to-guides/builders/setup-agent-client.mdx‎

Lines changed: 91 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -43,49 +43,115 @@ Agent clients allow you to easily communicate with other agents' APIs, enabling
4343

4444
<Steps>
4545

46-
1. **Install the Torus SDK**
46+
1. **Install the required dependencies**
4747

4848
```sh
49-
npm install @torus-network/sdk
49+
npm install @torus-network/sdk dotenv
50+
npm install -D @types/node
5051
```
5152

52-
2. **Create a keypair**
53+
2. **Create environment configuration**
5354

54-
```ts
55-
import { AgentClient, Keypair } from "@torus-network/sdk";
55+
Create a `.env` file in your project root:
56+
57+
```env
58+
AGENT_MNEMONIC=your twelve word mnemonic phrase goes here exactly like this
59+
TARGET_AGENT_URL=http://localhost:3000
60+
NODE_ENV=development
61+
```
62+
63+
3. **Create the client with proper error handling**
5664

57-
const keypair = new Keypair(
58-
"your twelve word mnemonic phrase goes here exactly like this"
59-
);
65+
```ts
66+
import { AgentClient, Keypair } from "@torus-network/sdk/agent-client";
67+
import dotenv from "dotenv";
68+
69+
// Load environment variables
70+
dotenv.config();
71+
72+
async function createClient() {
73+
try {
74+
if (!process.env.AGENT_MNEMONIC) {
75+
throw new Error("AGENT_MNEMONIC environment variable is required");
76+
}
77+
78+
const keypair = new Keypair(process.env.AGENT_MNEMONIC);
79+
80+
const client = new AgentClient({
81+
keypair,
82+
baseUrl: process.env.TARGET_AGENT_URL || "http://localhost:3000",
83+
});
84+
85+
console.log("Agent client initialized successfully");
86+
return client;
87+
} catch (error) {
88+
console.error("Failed to create agent client:", error);
89+
throw error;
90+
}
91+
}
6092
```
6193

62-
3. **Create the client**
94+
4. **Make API calls with comprehensive error handling**
6395

6496
```ts
65-
const client = new AgentClient({
66-
keypair,
67-
baseUrl: "http://localhost:3000", // Target agent server URL
68-
});
97+
async function callAgent(client: AgentClient, endpoint: string, data: any) {
98+
try {
99+
console.log(`Calling endpoint: ${endpoint} with data:`, data);
100+
101+
const response = await client.call({
102+
endpoint,
103+
data,
104+
});
105+
106+
if (response.success) {
107+
console.log("Response received:", response.data);
108+
return response.data;
109+
} else {
110+
console.error("API call failed:", response.error);
111+
throw new Error(`API call failed: ${response.error}`);
112+
}
113+
} catch (error) {
114+
console.error(`Error calling ${endpoint}:`, error);
115+
throw error;
116+
}
117+
}
69118
```
70119

71-
4. **Make API calls**
120+
5. **Complete example with initialization and usage**
72121

73122
```ts
74-
const response = await client.call({
75-
endpoint: "hello",
76-
data: { name: "Alice" },
77-
});
78-
79-
if (response.success) {
80-
console.log("Response:", response.data);
81-
} else {
82-
console.error("Error:", response.error);
123+
async function main() {
124+
try {
125+
// Initialize the client
126+
const client = await createClient();
127+
128+
// Make API calls
129+
const helloResponse = await callAgent(client, "hello", {
130+
name: "Alice"
131+
});
132+
133+
console.log("Hello response:", helloResponse);
134+
135+
// You can make multiple calls
136+
const anotherResponse = await callAgent(client, "hello", {
137+
name: "Bob"
138+
});
139+
140+
console.log("Another response:", anotherResponse);
141+
142+
} catch (error) {
143+
console.error("Application failed:", error);
144+
process.exit(1);
145+
}
83146
}
147+
148+
// Run the client
149+
main();
84150
```
85151

86-
5. **All Done**
152+
6. **All Done**
87153

88-
Your agent client is now ready to communicate with other agents' APIs.
154+
Your agent client is now ready to communicate with other agents' APIs with proper error handling and environment configuration.
89155

90156
</Steps>
91157

‎src/content/docs/how-to-guides/builders/setup-agent-server.mdx‎

Lines changed: 100 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Setup Agent Server
3-
description: Step-by-step guide to build APIs with the Agent class from torus-ts-sdk.
3+
description: Step-by-step guide to build APIs with the Agent class from @torus-network/sdk.
44
---
55

66
import {
@@ -44,61 +44,123 @@ Agent servers allow you to create APIs that other agents can discover and intera
4444

4545
<Steps>
4646

47-
1. **Install the Torus SDK**
47+
1. **Install the required dependencies**
4848

4949
```sh
50-
npm install @torus-network/sdk
50+
npm install @torus-network/sdk dotenv zod
51+
npm install -D @types/node
5152
```
5253

53-
2. **Create a basic server**
54+
2. **Create environment configuration**
55+
56+
Create a `.env` file in your project root:
57+
58+
```env
59+
AGENT_KEY=your-agent-wallet-address
60+
AGENT_MNEMONIC=your twelve word mnemonic phrase goes here exactly like this
61+
PORT=3000
62+
NODE_ENV=development
63+
```
64+
65+
3. **Create the server with proper error handling**
5466

5567
```ts
56-
import { Agent } from "@torus-network/sdk";
68+
import { Agent } from "@torus-network/sdk/agent";
5769
import { z } from "zod";
58-
59-
const agent = new AgentServer({
60-
agentKey: "your-agent-wallet-address", // Your registered agent's wallet address
61-
port: 3000,
62-
docs: {
63-
info: {
64-
title: "My Agent API",
65-
version: "1.0.0",
66-
},
67-
},
68-
});
70+
import dotenv from "dotenv";
71+
72+
// Load environment variables
73+
dotenv.config();
74+
75+
async function createAgent() {
76+
try {
77+
const agent = new Agent({
78+
agentKey: process.env.AGENT_KEY!,
79+
port: parseInt(process.env.PORT || "3000"),
80+
docs: {
81+
info: {
82+
title: "My Agent API",
83+
version: "1.0.0",
84+
},
85+
},
86+
});
87+
88+
return agent;
89+
} catch (error) {
90+
console.error("Failed to create agent:", error);
91+
process.exit(1);
92+
}
93+
}
6994
```
7095

71-
3. **Add an endpoint**
96+
4. **Add endpoints with comprehensive error handling**
7297

7398
```ts
74-
agent.endpoint({
75-
endpoint: "hello",
76-
schema: {
77-
input: z.object({
78-
name: z.string(),
79-
}),
80-
output: z.object({
81-
message: z.string(),
82-
}),
83-
},
84-
handler: async ({ input }) => {
85-
return {
86-
message: `Hello, ${input.name}!`,
87-
};
88-
},
89-
});
99+
async function setupEndpoints(agent: Agent) {
100+
try {
101+
agent.method({
102+
endpoint: "hello",
103+
schema: {
104+
input: z.object({
105+
name: z.string(),
106+
}),
107+
output: z.object({
108+
message: z.string(),
109+
}),
110+
},
111+
handler: async ({ input }) => {
112+
try {
113+
return {
114+
message: `Hello, ${input.name}!`,
115+
};
116+
} catch (error) {
117+
console.error("Error in hello endpoint:", error);
118+
throw error;
119+
}
120+
},
121+
});
122+
123+
console.log("Endpoints configured successfully");
124+
} catch (error) {
125+
console.error("Failed to setup endpoints:", error);
126+
throw error;
127+
}
128+
}
90129
```
91130

92-
4. **Start the server**
131+
5. **Start the server with proper initialization**
93132

94133
```ts
95-
agent.start();
96-
console.log("Agent server running on http://localhost:3000");
134+
async function startServer() {
135+
try {
136+
const agent = await createAgent();
137+
await setupEndpoints(agent);
138+
139+
agent.run();
140+
141+
const port = process.env.PORT || 3000;
142+
console.log(`Agent server running on http://localhost:${port}`);
143+
console.log(`API documentation available at http://localhost:${port}/docs`);
144+
145+
// Graceful shutdown handling
146+
process.on('SIGTERM', () => {
147+
console.log('Received SIGTERM, shutting down gracefully');
148+
process.exit(0);
149+
});
150+
151+
} catch (error) {
152+
console.error("Failed to start server:", error);
153+
process.exit(1);
154+
}
155+
}
156+
157+
// Start the server
158+
startServer();
97159
```
98160

99-
5. **All Done**
161+
6. **All Done**
100162

101-
Your agent server is now running and available at `http://localhost:3000/docs` for API documentation.
163+
Your agent server is now running with proper error handling and environment configuration. The API documentation is available at `http://localhost:3000/docs`.
102164

103165
</Steps>
104166

0 commit comments

Comments
 (0)