Skip to content

Commit af372ec

Browse files
CopilotCopilot
committed
Implement Phase 1.2 Schema Design & Validation complete
1 parent 1e9aa50 commit af372ec

26 files changed

+3176
-68
lines changed

‎.eslintrc.js‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,15 @@ module.exports = {
5555
rules: {
5656
'@typescript-eslint/no-var-requires': 'off'
5757
}
58+
},
59+
{
60+
files: ['scripts/**/*.ts'],
61+
parserOptions: {
62+
project: null
63+
},
64+
rules: {
65+
'no-console': 'off'
66+
}
5867
}
5968
]
6069
};

‎docs/api/configuration-schema.md‎

Lines changed: 282 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,282 @@
1+
# Configuration Schema Reference
2+
3+
This document provides a comprehensive reference for the Agents CLI configuration schema.
4+
5+
## Overview
6+
7+
Agents CLI uses a JSON or YAML configuration file to define agents, workflows, and their behavior.
8+
The configuration is validated using Zod schemas to ensure correctness before execution.
9+
10+
## Configuration File Structure
11+
12+
```typescript
13+
{
14+
"metadata": {
15+
"name": "string",
16+
"description": "string",
17+
"version": "string",
18+
"author": "string"
19+
},
20+
"agents": {
21+
"[agent_id]": {
22+
// Agent configuration
23+
}
24+
},
25+
"workflow": {
26+
// Workflow configuration
27+
}
28+
}
29+
```
30+
31+
## Metadata (Optional)
32+
33+
Configuration metadata for documentation and versioning.
34+
35+
| Field | Type | Required | Description |
36+
| ------------- | ------ | -------- | -------------------------------------- |
37+
| `name` | string | No | Configuration name |
38+
| `description` | string | No | Configuration description |
39+
| `version` | string | No | Configuration version (default: "1.0") |
40+
| `author` | string | No | Configuration author |
41+
| `created` | string | No | Creation timestamp (ISO 8601) |
42+
| `updated` | string | No | Last update timestamp (ISO 8601) |
43+
44+
## Agents Configuration
45+
46+
The `agents` object contains one or more agent configurations, keyed by agent ID.
47+
48+
### Agent Configuration
49+
50+
| Field | Type | Required | Default | Description |
51+
| --------------- | ------ | -------- | -------- | ---------------------------------- |
52+
| `name` | string | Yes | - | Human-readable agent name |
53+
| `instructions` | string | Yes | - | Agent's system instructions/prompt |
54+
| `model` | string | No | "gpt-4o" | OpenAI model to use |
55+
| `modelSettings` | object | No | - | Model fine-tuning parameters |
56+
| `tools` | array | No | [] | Tools available to the agent |
57+
| `guardrails` | array | No | [] | Safety guardrails |
58+
| `handoffs` | array | No | [] | Other agents to hand off to |
59+
| `memory` | object | No | - | Memory configuration |
60+
| `context` | object | No | - | Context management settings |
61+
| `metadata` | object | No | - | Custom metadata |
62+
63+
### Model Options
64+
65+
Supported models:
66+
67+
- `gpt-4o` (default)
68+
- `gpt-4o-mini`
69+
- `gpt-4-turbo`
70+
- `gpt-4`
71+
- `gpt-3.5-turbo`
72+
- `o1`
73+
- `o1-mini`
74+
75+
### Model Settings
76+
77+
| Field | Type | Range | Description |
78+
| ------------------- | ------ | ------- | -------------------------- |
79+
| `temperature` | number | 0-2 | Sampling temperature |
80+
| `top_p` | number | 0-1 | Nucleus sampling parameter |
81+
| `max_tokens` | number | >0 | Maximum tokens in response |
82+
| `presence_penalty` | number | -2 to 2 | Presence penalty |
83+
| `frequency_penalty` | number | -2 to 2 | Frequency penalty |
84+
85+
### Tools Configuration
86+
87+
Tools can be specified as:
88+
89+
1. **Built-in tool names** (strings):
90+
- `file_operations`
91+
- `git_tools`
92+
- `web_search`
93+
- `security_scanner`
94+
95+
2. **MCP Server configuration** (object):
96+
97+
```json
98+
{
99+
"type": "mcp_server",
100+
"name": "server-name",
101+
"command": "npx",
102+
"args": ["-y", "@modelcontextprotocol/server-filesystem"],
103+
"env": { "PATH": "/usr/bin" }
104+
}
105+
```
106+
107+
3. **Custom function tool** (object):
108+
```json
109+
{
110+
"type": "custom_function",
111+
"name": "my_tool",
112+
"description": "Tool description",
113+
"parameters": {},
114+
"handler": "./path/to/handler.js"
115+
}
116+
```
117+
118+
### Guardrails
119+
120+
Built-in guardrails:
121+
122+
- `no_destructive_operations` - Prevent destructive file/git operations
123+
- `require_approval` - Require human approval for actions
124+
- `file_access_control` - Restrict file system access
125+
- `rate_limiting` - Limit API call rate
126+
- `content_filtering` - Filter sensitive content
127+
128+
### Handoffs
129+
130+
Handoffs enable agent-to-agent delegation. Specify as:
131+
132+
- **Simple string**: Agent ID to hand off to
133+
- **Handoff rule object**:
134+
```json
135+
{
136+
"target_agent": "agent_id",
137+
"condition": "when to hand off",
138+
"priority": 1
139+
}
140+
```
141+
142+
### Memory Configuration
143+
144+
| Field | Type | Default | Description |
145+
| ------------- | ------- | --------- | ------------------------------------------- |
146+
| `enabled` | boolean | true | Enable conversation memory |
147+
| `max_turns` | number | - | Maximum turns to remember |
148+
| `max_tokens` | number | - | Maximum tokens to store |
149+
| `persistence` | string | "session" | Persistence level: none, session, permanent |
150+
151+
### Context Configuration
152+
153+
| Field | Type | Default | Description |
154+
| -------------------- | ------- | ------- | ------------------------------ |
155+
| `max_context_length` | number | - | Maximum context length |
156+
| `context_window` | number | - | Context window size |
157+
| `summarization` | boolean | false | Enable automatic summarization |
158+
159+
## Workflow Configuration
160+
161+
The `workflow` object defines how agents are orchestrated.
162+
163+
| Field | Type | Required | Default | Description |
164+
| ------------- | ------ | -------- | ------------ | ---------------------- |
165+
| `entry_point` | string | Yes | - | Agent ID to start with |
166+
| `pattern` | string | No | "sequential" | Execution pattern |
167+
| `output` | object | No | - | Output format settings |
168+
| `limits` | object | No | - | Resource limits |
169+
170+
### Workflow Patterns
171+
172+
- `sequential` - Execute agents in sequence
173+
- `handoff_chain` - Agents hand off to each other
174+
- `parallel` - Execute agents in parallel
175+
- `conditional` - Conditional agent execution
176+
177+
### Output Format
178+
179+
| Field | Type | Default | Description |
180+
| ------------------ | ------- | ------- | ----------------------------------------------- |
181+
| `format` | string | "json" | Output format: json, text, markdown, structured |
182+
| `stream` | boolean | false | Enable streaming output |
183+
| `include_metadata` | boolean | true | Include metadata in output |
184+
| `include_trace` | boolean | false | Include execution trace |
185+
186+
### Resource Limits
187+
188+
| Field | Type | Default | Description |
189+
| ----------------------- | ------ | ------- | --------------------- |
190+
| `max_turns` | number | 10 | Maximum agent turns |
191+
| `timeout` | number | 300 | Timeout in seconds |
192+
| `max_tokens` | number | - | Maximum total tokens |
193+
| `max_concurrent_agents` | number | - | Max concurrent agents |
194+
195+
## Environment Variables
196+
197+
Configuration files support environment variable substitution using the syntax:
198+
199+
- `${VAR_NAME}` - Use environment variable
200+
- `${VAR_NAME:-default}` - Use variable with default fallback
201+
202+
Example:
203+
204+
```json
205+
{
206+
"agents": {
207+
"assistant": {
208+
"model": "${OPENAI_MODEL:-gpt-4o}",
209+
"name": "Assistant"
210+
}
211+
}
212+
}
213+
```
214+
215+
## Configuration File Discovery
216+
217+
Agents CLI automatically discovers configuration files in this order:
218+
219+
1. `agents-cli.json`
220+
2. `agents-cli.yaml`
221+
3. `agents-cli.yml`
222+
4. `agents.config.json`
223+
5. `agents.config.yaml`
224+
6. `agents.config.yml`
225+
7. `.agents-cli.json`
226+
8. `.agents-cli.yaml`
227+
228+
## Examples
229+
230+
See the [examples directory](../../examples/) for complete configuration examples:
231+
232+
- [simple.json](../../examples/simple.json) - Minimal single-agent example
233+
- [code-review.json](../../examples/code-review.json) - Multi-agent code review
234+
- [architecture-review.json](../../examples/architecture-review.json) - Architecture analysis
235+
236+
## JSON Schema
237+
238+
The complete JSON Schema is available at
239+
[schemas/configuration.schema.json](schemas/configuration.schema.json) for IDE integration and
240+
validation.
241+
242+
## Validation
243+
244+
Validate your configuration using the CLI:
245+
246+
```bash
247+
# Basic validation
248+
agents-cli validate config.json
249+
250+
# Verbose output
251+
agents-cli validate config.json --verbose
252+
253+
# JSON output
254+
agents-cli validate config.json --format json
255+
256+
# Hide warnings
257+
agents-cli validate config.json --no-warnings
258+
```
259+
260+
## IDE Integration
261+
262+
For IDE autocomplete and validation, configure your editor to use the JSON schema:
263+
264+
### VS Code
265+
266+
Add to `.vscode/settings.json`:
267+
268+
```json
269+
{
270+
"json.schemas": [
271+
{
272+
"fileMatch": ["**/agents-cli.json", "**/agents.config.json"],
273+
"url": "./docs/api/schemas/configuration.schema.json"
274+
}
275+
]
276+
}
277+
```
278+
279+
### JetBrains IDEs
280+
281+
Go to Settings → Languages & Frameworks → Schemas and DTDs → JSON Schema Mappings and add the schema
282+
mapping.

0 commit comments

Comments
 (0)