@indra.ai/deva 1.64.55 → 1.64.92

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,159 @@
1
+ ---
2
+ layout: page
3
+ title: "Step 3: The agent file"
4
+ permalink: /guide/step-3/
5
+ description: Write agent.json, which describes who the Deva is, including its vars and its own context labels.
6
+ image: /assets/banner.png
7
+ ---
8
+
9
+ {% assign guide = site.data.guide.DATA %}
10
+ {% assign step = guide.steps | where: "step", 3 | first %}
11
+ {% assign next = guide.steps | where: "step", 4 | first %}
12
+
13
+ {{ step.describe }}
14
+
15
+ The client file says who is talking. The **agent** file says who is listening: your Deva's identity, how it shows up in the prompt, its profile, and its **vars**. Vars are the Deva's own settings and words, and they live right here in the agent file next to the profile.
16
+
17
+ ## 1. The wrapper
18
+
19
+ The agent file uses the same outer shape as the client file. Open `data/agent.json` and start with this:
20
+
21
+ ```json
22
+ {
23
+ "name": "AGENT",
24
+ "describe": "Hello Deva agent file",
25
+ "copyright": "Copyright ©2026 Your Name; All rights reserved.",
26
+ "VLA": {},
27
+ "DATA": {
28
+ }
29
+ }
30
+ ```
31
+
32
+ Everything the Deva reads goes inside `DATA`. The `VLA` sits above it, at the top level.
33
+
34
+ ## 2. The agent's license (VLA)
35
+
36
+ The client file and the agent file each carry a VLA, and the two do different jobs:
37
+
38
+ - The **client VLA**, inside the client's `DATA` from Step 2, is checked when the Deva starts. It's what gives the client access to Deva Core.
39
+ - The **agent VLA**, at the top of this file, belongs to the Deva itself. It isn't checked at start-up. It gets compared later, when something accesses this Deva. Custom Devas do that comparison in their own `onInit` event.
40
+
41
+ For Hello Deva, the agent VLA is the same record that ships with Deva Core. Print it the same way you did in Step 2:
42
+
43
+ ```bash
44
+ node -e "console.log(JSON.stringify(require('./node_modules/{{ guide.package }}/package.json').VLA, null, 2))"
45
+ ```
46
+
47
+ Copy the whole object it prints into the top-level `"VLA"`, unchanged.
48
+
49
+ While you're building, the agent's settings live in `agent.json`. When a Deva is ready for production, the same settings move into its `package.json`, so the entity, its data and its package travel together as one file. The VLA stays at the top level either way.
50
+
51
+ ## 3. Identity and prompt
52
+
53
+ Inside `DATA`, give the Deva an `id`, a `key` and a `prompt`:
54
+
55
+ ```json
56
+ "id": "00000000000000000002",
57
+ "key": "hello",
58
+ "prompt": {
59
+ "emoji": "👋",
60
+ "text": "hello",
61
+ "colors": {
62
+ "label": {"R": 0, "G": 150, "B": 255},
63
+ "text": {"R": 101, "G": 192, "B": 255}
64
+ }
65
+ },
66
+ ```
67
+
68
+ - `id` is a unique id for this Deva. Make it different from the client's `id`.
69
+ - `key` is the Deva's short name. Other Devas and the client's `devas` settings refer to it by this key, so keep it short, lowercase and unique.
70
+ - `prompt` works the same as in the client file: the emoji, label and colors the Deva uses when it talks.
71
+
72
+ ## 4. Profile
73
+
74
+ `profile` describes the Deva:
75
+
76
+ ```json
77
+ "profile": {
78
+ "name": "Hello Deva",
79
+ "describe": "My first Deva. It says hello."
80
+ },
81
+ ```
82
+
83
+ `name` is the one that matters most. The Deva uses it to sign what it says. The profile can also carry its own `warning`, `notice`, `copyright`, `owner` and `creator`. If you leave those out, the Deva uses Deva Core's defaults.
84
+
85
+ ## 5. Vars
86
+
87
+ `vars` holds the Deva's own values. Anything you put here, the Deva can read later as `this.vars`. Start with one plain value and a `context` map:
88
+
89
+ ```json
90
+ "vars": {
91
+ "greeting": "Hello World",
92
+ "context": {
93
+ "hello": "👋 Saying hello"
94
+ }
95
+ }
96
+ ```
97
+
98
+ - `greeting` is a plain value. You'll use it in Step {{ next.step | plus: 1 }} when the Deva learns to say hello.
99
+ - `context` is a map of labels for what the Deva is doing. Each Deva defines its own. When the Deva calls `this.context('hello')`, it announces "👋 Saying hello".
100
+
101
+ The key is `context`, singular. Add more labels as your Deva learns more.
102
+
103
+ ## The whole file
104
+
105
+ Put together, `data/agent.json` looks like this. Your VLA record goes in place of `"uid": "your full VLA record"`, and it must be the whole record, copied unchanged:
106
+
107
+ ```json
108
+ {
109
+ "name": "AGENT",
110
+ "describe": "Hello Deva agent file",
111
+ "copyright": "Copyright ©2026 Your Name; All rights reserved.",
112
+ "VLA": {
113
+ "uid": "your full VLA record"
114
+ },
115
+ "DATA": {
116
+ "id": "00000000000000000002",
117
+ "key": "hello",
118
+ "prompt": {
119
+ "emoji": "👋",
120
+ "text": "hello",
121
+ "colors": {
122
+ "label": {"R": 0, "G": 150, "B": 255},
123
+ "text": {"R": 101, "G": 192, "B": 255}
124
+ }
125
+ },
126
+ "profile": {
127
+ "name": "Hello Deva",
128
+ "describe": "My first Deva. It says hello."
129
+ },
130
+ "vars": {
131
+ "greeting": "Hello World",
132
+ "context": {
133
+ "hello": "👋 Saying hello"
134
+ }
135
+ }
136
+ }
137
+ }
138
+ ```
139
+
140
+ Check that it's valid JSON:
141
+
142
+ ```bash
143
+ node -e "JSON.parse(require('fs').readFileSync('data/agent.json')); console.log('agent.json ok')"
144
+ ```
145
+
146
+ You should see:
147
+
148
+ ```
149
+ agent.json ok
150
+ ```
151
+
152
+ ## What you did
153
+
154
+ {% for item in step.learn %}- {{ item }}
155
+ {% endfor %}
156
+
157
+ ## Next
158
+
159
+ In **[Step {{ next.step }}: {{ next.title }}]({{ next.permalink }})** you'll write `index.js`, load both files, and pass the agent's vars to your Deva.
@@ -0,0 +1,173 @@
1
+ ---
2
+ layout: page
3
+ title: "Step 4: Wire it together"
4
+ permalink: /guide/step-4/
5
+ description: Import the client and agent files, build the info block from your package.json, and create the Deva.
6
+ image: /assets/banner.png
7
+ ---
8
+
9
+ {% assign guide = site.data.guide.DATA %}
10
+ {% assign step = guide.steps | where: "step", 4 | first %}
11
+ {% assign next = guide.steps | where: "step", 5 | first %}
12
+ {% assign life = guide.steps | where: "step", 6 | first %}
13
+
14
+ {{ step.describe }}
15
+
16
+ You have a client file and an agent file. Now you'll write `index.js`, which loads both, builds an info block from your `package.json`, and creates {{ guide.deva }}. You won't start it yet. That comes in Step {{ life.step }}.
17
+
18
+ ## 1. Fill in package.json
19
+
20
+ The Deva's info block is built from your `package.json`, so add an `id`, a `description` and a `copyright` to the file you created in Step 1:
21
+
22
+ ```bash
23
+ npm pkg set id="00000000000000000003"
24
+ npm pkg set description="My first Deva. It says hello."
25
+ npm pkg set copyright="Copyright ©2026 Your Name; All rights reserved."
26
+ ```
27
+
28
+ Make the `id` different from the client and agent ids. The description and copyright can be your own words. Your `package.json` should now include these entries:
29
+
30
+ ```json
31
+ "id": "00000000000000000003",
32
+ "name": "hello-deva",
33
+ "version": "1.0.0",
34
+ "description": "My first Deva. It says hello.",
35
+ "copyright": "Copyright ©2026 Your Name; All rights reserved.",
36
+ "type": "module"
37
+ ```
38
+
39
+ ## 2. Load the files
40
+
41
+ Open `index.js` and start with the imports:
42
+
43
+ ```javascript
44
+ import Deva from '{{ guide.package }}';
45
+ import pkg from './package.json' with {type:'json'};
46
+ import Agent from './data/agent.json' with {type:'json'};
47
+ import Client from './data/client.json' with {type:'json'};
48
+ ```
49
+
50
+ The `with {type:'json'}` part is required. It's an import attribute that tells Node the file is JSON.
51
+
52
+ The JSON files have a wrapper, and everything the Deva reads is inside `DATA`. Pull that out:
53
+
54
+ ```javascript
55
+ const agent = Agent.DATA;
56
+ const client = Client.DATA;
57
+ ```
58
+
59
+ You won't use `client` until the Deva starts in Step {{ life.step }}, but loading it now keeps both files in one place.
60
+
61
+ ## 3. Build the info block
62
+
63
+ `info` is the Deva's own package information. Build it from your `package.json`, plus the folder this file is in and the agent's VLA from the top of the agent file:
64
+
65
+ ```javascript
66
+ const info = {
67
+ id: pkg.id,
68
+ name: pkg.name,
69
+ describe: pkg.description,
70
+ version: pkg.version,
71
+ copyright: pkg.copyright,
72
+ dir: import.meta.dirname,
73
+ VLA: Agent.VLA,
74
+ };
75
+ ```
76
+
77
+ - `describe` is the one name that differs: `package.json` calls it `description`, the info block calls it `describe`.
78
+ - `dir` is the folder `index.js` lives in.
79
+ - `VLA` is the agent's own license, from the top level of `agent.json`, outside `DATA`. That's why it reads `Agent.VLA` and not `agent.VLA`. It's the license that gets compared later when something accesses this Deva. The client's VLA stays in the client file, and the core checks it when the Deva starts in Step {{ life.step }}.
80
+
81
+ ## 4. Create the Deva
82
+
83
+ Pass `info`, the agent's identity fields, and the agent's vars:
84
+
85
+ ```javascript
86
+ const hello = new Deva({
87
+ info,
88
+ agent: {
89
+ id: agent.id,
90
+ key: agent.key,
91
+ prompt: agent.prompt,
92
+ profile: agent.profile,
93
+ },
94
+ vars: agent.vars,
95
+ });
96
+
97
+ console.log(hello.vars.greeting);
98
+ console.log(hello.vars.context);
99
+ console.log(hello.status());
100
+ ```
101
+
102
+ `vars: agent.vars` is how the greeting and context labels you wrote in the agent file become `hello.vars`. The Deva exists now, but it hasn't started. You'll start it with `init(client)` in [Step {{ life.step }}: {{ life.title }}]({{ life.permalink }}).
103
+
104
+ ## The whole file
105
+
106
+ ```javascript
107
+ import Deva from '{{ guide.package }}';
108
+ import pkg from './package.json' with {type:'json'};
109
+ import Agent from './data/agent.json' with {type:'json'};
110
+ import Client from './data/client.json' with {type:'json'};
111
+
112
+ const agent = Agent.DATA;
113
+ const client = Client.DATA;
114
+
115
+ const info = {
116
+ id: pkg.id,
117
+ name: pkg.name,
118
+ describe: pkg.description,
119
+ version: pkg.version,
120
+ copyright: pkg.copyright,
121
+ dir: import.meta.dirname,
122
+ VLA: Agent.VLA,
123
+ };
124
+
125
+ const hello = new Deva({
126
+ info,
127
+ agent: {
128
+ id: agent.id,
129
+ key: agent.key,
130
+ prompt: agent.prompt,
131
+ profile: agent.profile,
132
+ },
133
+ vars: agent.vars,
134
+ });
135
+
136
+ console.log(hello.vars.greeting);
137
+ console.log(hello.vars.context);
138
+ console.log(hello.status());
139
+ ```
140
+
141
+ Run it:
142
+
143
+ ```bash
144
+ {{ guide.run }}
145
+ ```
146
+
147
+ You should see:
148
+
149
+ ```
150
+ Hello World
151
+ { hello: '👋 Saying hello' }
152
+ ⭕️ OFFLINE
153
+ ```
154
+
155
+ The first two lines are the vars from your agent file. `⭕️ OFFLINE` is the right answer here: the Deva has been created but not started.
156
+
157
+ ## If something goes wrong
158
+
159
+ | You see | What it means |
160
+ |---|---|
161
+ | `needs an import attribute of "type: json"` | An import is missing `with {type:'json'}`. |
162
+ | `Cannot find module` for `agent.json` or `client.json` | The path is wrong. The files live in `data/`, so the imports should be `./data/agent.json` and `./data/client.json`. |
163
+ | `undefined` instead of `Hello World` | `vars: agent.vars` is missing, or `agent` is the wrapper instead of `Agent.DATA`. |
164
+ | `SyntaxError` in `agent.json` or `client.json` | The JSON isn't valid. Run the JSON check from Step 2 or Step 3 again. |
165
+
166
+ ## What you did
167
+
168
+ {% for item in step.learn %}- {{ item }}
169
+ {% endfor %}
170
+
171
+ ## Next
172
+
173
+ In **[Step {{ next.step }}: {{ next.title }}]({{ next.permalink }})** you'll add one func, one method and one listener, and see when to use each.
@@ -0,0 +1,222 @@
1
+ ---
2
+ layout: page
3
+ title: "Step 5: Give it skills"
4
+ permalink: /guide/step-5/
5
+ description: Add one func, one method and one listener, and see when to use each.
6
+ image: /assets/banner.png
7
+ ---
8
+
9
+ {% assign guide = site.data.guide.DATA %}
10
+ {% assign step = guide.steps | where: "step", 5 | first %}
11
+ {% assign next = guide.steps | where: "step", 6 | first %}
12
+
13
+ {{ step.describe }}
14
+
15
+ Your Deva has a name, a profile and vars, but it can't do anything yet. In this step you'll give it three kinds of skills: a **func**, a **method** and a **listener**. You'll add all three to the `new Deva()` block you wrote in Step 4. The Deva still won't start in this step. You'll start it and see the skills work in Step {{ next.step }}.
16
+
17
+ ## 1. Three kinds of skills
18
+
19
+ Each kind has its own job:
20
+
21
+ | Kind | Where it goes | Who uses it | Use it when |
22
+ |---|---|---|---|
23
+ | func | `func` | Only the Deva itself, as `this.func.name()` | You have internal work that more than one method might need, such as building text or reading a database. Nobody outside the Deva can call a func by name. |
24
+ | method | `methods` | Anyone who asks the Deva a question, as `/name` | You want a public command. A method is what runs when someone asks the Deva to do something. |
25
+ | listener | `listeners` | The event bus | You want the Deva to react when an event happens, no matter who caused it. |
26
+
27
+ A good rule: put the work in a func, let a method call that func, and use a listener to watch what happens.
28
+
29
+ All three are written as normal functions, like `greet(name) {}`. Don't write them as arrow functions. When the Deva starts, Deva Core binds every func, method and listener to the Deva, so `this` inside them is the Deva. That's how they can reach `this.vars`, `this.func` and the rest. An arrow function can't be bound, so `this` would be wrong inside it.
30
+
31
+ ## 2. Add a func
32
+
33
+ Add a `func` block inside `new Deva()`, right after `vars: agent.vars,`:
34
+
35
+ ```javascript
36
+ func: {
37
+ greet(name) {
38
+ if (!name) return `${this.vars.greeting}.`;
39
+ return `${this.vars.greeting}, and hello to ${name}.`;
40
+ },
41
+ },
42
+ ```
43
+
44
+ `greet` builds the Deva's greeting from `this.vars.greeting`, the `Hello World` you wrote in your agent file in Step 3. If it's given a name, it adds a hello to that name.
45
+
46
+ ## 3. Add a method
47
+
48
+ Add a `methods` block right after the `func` block:
49
+
50
+ ```javascript
51
+ methods: {
52
+ hello(packet) {
53
+ this.context('hello', packet.q.text);
54
+ return new Promise(resolve => {
55
+ const text = this.func.greet(packet.q.text);
56
+ return resolve({
57
+ text,
58
+ html: `<p>${text}</p>`,
59
+ data: {
60
+ greeting: this.vars.greeting,
61
+ name: packet.q.text,
62
+ },
63
+ });
64
+ });
65
+ },
66
+ },
67
+ ```
68
+
69
+ The method's name is its command. Once the Deva is running, asking it `/hello Quinn` runs `methods.hello`. Here's what each part does:
70
+
71
+ - **`packet`** is the question packet the Deva builds for you. The text after the command is in `packet.q.text`, so for `/hello Quinn` it's `Quinn`.
72
+ - **`this.context('hello', packet.q.text)`** sets the Deva's context to the `hello` label from `vars.context` in your agent file, which is `👋 Saying hello`. That's why you wrote that label in Step 3.
73
+ - **`this.func.greet(packet.q.text)`** does the actual work by calling the func you just added.
74
+ - **The method returns a Promise.** This is required. The core waits for the Promise and then puts your result into the answer.
75
+ - **The result has `text`, `html` and `data`.** These become `a.text`, `a.html` and `a.data` in the answer packet. You can also resolve a plain string, and the core will use it as the text.
76
+
77
+ ## 4. Add a listener
78
+
79
+ Add a `listeners` block right after the `methods` block:
80
+
81
+ ```javascript
82
+ listeners: {
83
+ 'devacore:question'(packet) {
84
+ console.log(`👂 heard: ${packet.q.text}`);
85
+ },
86
+ },
87
+ ```
88
+
89
+ The name of a listener is the event it listens for. `devacore:question` is the event Deva Core sends every time the Deva is asked a question, before it answers. The listener receives a copy of the question packet, so the question's text is in `packet.q.text`.
90
+
91
+ The event name has quotes around it because it contains a colon.
92
+
93
+ ## 5. Check them before the Deva starts
94
+
95
+ Replace the three `console.log` lines from Step 4 with these:
96
+
97
+ ```javascript
98
+ console.log(hello.status());
99
+ console.log('func:', Object.keys(hello.func));
100
+ console.log('methods:', Object.keys(hello.methods));
101
+ console.log('listeners:', Object.keys(hello.listeners));
102
+ console.log('heard:', hello.talk('devacore:question'));
103
+ console.log('answer:', await hello.question('/hello Quinn'));
104
+ ```
105
+
106
+ The Deva hasn't started, so this check shows what's ready and what isn't:
107
+
108
+ - The first line shows the Deva is still offline.
109
+ - The next three lines list the skills you added. The Deva is holding them, ready for start-up.
110
+ - `hello.talk('devacore:question')` sends that event and reports whether anything heard it. It answers `false` because the listener isn't connected to the event bus yet. Listeners are connected when the Deva starts.
111
+ - `hello.question('/hello Quinn')` asks the Deva to run your method. It answers `⭕️ OFFLINE` because a Deva only answers questions after it has started.
112
+
113
+ Binding happens at start-up too. Before then, `this` inside a func isn't the Deva yet, so don't call `hello.func.greet()` directly to test it. You'll see all three skills work in Step {{ next.step }}.
114
+
115
+ ## The whole file
116
+
117
+ ```javascript
118
+ import Deva from '{{ guide.package }}';
119
+ import pkg from './package.json' with {type:'json'};
120
+ import Agent from './data/agent.json' with {type:'json'};
121
+ import Client from './data/client.json' with {type:'json'};
122
+
123
+ const agent = Agent.DATA;
124
+ const client = Client.DATA;
125
+
126
+ const info = {
127
+ id: pkg.id,
128
+ name: pkg.name,
129
+ describe: pkg.description,
130
+ version: pkg.version,
131
+ copyright: pkg.copyright,
132
+ dir: import.meta.dirname,
133
+ VLA: Agent.VLA,
134
+ };
135
+
136
+ const hello = new Deva({
137
+ info,
138
+ agent: {
139
+ id: agent.id,
140
+ key: agent.key,
141
+ prompt: agent.prompt,
142
+ profile: agent.profile,
143
+ },
144
+ vars: agent.vars,
145
+ func: {
146
+ greet(name) {
147
+ if (!name) return `${this.vars.greeting}.`;
148
+ return `${this.vars.greeting}, and hello to ${name}.`;
149
+ },
150
+ },
151
+ methods: {
152
+ hello(packet) {
153
+ this.context('hello', packet.q.text);
154
+ return new Promise(resolve => {
155
+ const text = this.func.greet(packet.q.text);
156
+ return resolve({
157
+ text,
158
+ html: `<p>${text}</p>`,
159
+ data: {
160
+ greeting: this.vars.greeting,
161
+ name: packet.q.text,
162
+ },
163
+ });
164
+ });
165
+ },
166
+ },
167
+ listeners: {
168
+ 'devacore:question'(packet) {
169
+ console.log(`👂 heard: ${packet.q.text}`);
170
+ },
171
+ },
172
+ });
173
+
174
+ console.log(hello.status());
175
+ console.log('func:', Object.keys(hello.func));
176
+ console.log('methods:', Object.keys(hello.methods));
177
+ console.log('listeners:', Object.keys(hello.listeners));
178
+ console.log('heard:', hello.talk('devacore:question'));
179
+ console.log('answer:', await hello.question('/hello Quinn'));
180
+ ```
181
+
182
+ Run it:
183
+
184
+ ```bash
185
+ {{ guide.run }}
186
+ ```
187
+
188
+ You should see:
189
+
190
+ ```
191
+ ⭕️ OFFLINE
192
+ func: [ 'greet' ]
193
+ methods: [ 'hello' ]
194
+ listeners: [ 'devacore:question' ]
195
+ heard: false
196
+ answer: ⭕️ OFFLINE
197
+ ```
198
+
199
+ Every line here is correct for a Deva that hasn't started. Your skills are in place, the listener isn't connected yet, and questions wait until start-up.
200
+
201
+ ## What happens in Step {{ next.step }}
202
+
203
+ When you start the Deva in Step {{ next.step }}, the same three skills come to life. Asking `/hello Quinn` will make the listener print `👂 heard: Quinn`, and the answer's text will be `Hello World, and hello to Quinn.`, built by your method calling your func.
204
+
205
+ ## If something goes wrong
206
+
207
+ | You see | What it means |
208
+ |---|---|
209
+ | `Cannot read properties of undefined (reading 'greeting')` | `hello.func.greet()` was called directly before the Deva started. Before start-up, `this` isn't the Deva yet. Use the check in section 5 instead. |
210
+ | `Cannot read properties of undefined (reading 'vars')` | A func, method or listener was written as an arrow function, such as `greet: (name) => {}`. Write it as `greet(name) {}` so it can be bound to the Deva. |
211
+ | `.then is not a function` | A method returned a plain value instead of a Promise. Wrap the result in `new Promise(resolve => {})` as `hello` does. |
212
+ | `⛔️ METHOD NOT FOUND hello hi` | The command doesn't match a method name. `/hi` looks for `methods.hi`. |
213
+ | `SyntaxError: Unexpected token '{'` | A listener's event name is missing its quotes. Write `'devacore:question'(packet)`. |
214
+
215
+ ## What you did
216
+
217
+ {% for item in step.learn %}- {{ item }}
218
+ {% endfor %}
219
+
220
+ ## Next
221
+
222
+ In **[Step {{ next.step }}: {{ next.title }}]({{ next.permalink }})** you'll start the Deva with `init(client)`, watch it reach ready, ask it `/hello`, and read the stamped packet that comes back.