Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 20 additions & 1 deletion .github/workflows/agent-e2e.yml
Original file line number Diff line number Diff line change
Expand Up @@ -94,9 +94,27 @@ jobs:
mcp-testkit --transport http --port 3001 &
sleep 2

# Deterministic decision provider for suite 24 (Jev decision routing).
# Only decision inference is faked; chat LLM calls use the real keys.
- name: Start fake decision provider
run: |
node e2e/fixtures/fake-providers.mjs > fake-providers.log 2>&1 &
# Any HTTP status (the fake answers a bodyless GET with 400) means it is listening.
for i in $(seq 1 20); do
code=$(curl -s -o /dev/null -w '%{http_code}' http://localhost:9911/ || true)
if [ "$code" != "000" ]; then echo "fake providers ready"; exit 0; fi
sleep 0.5
done
echo "::error::fake providers did not start"
cat fake-providers.log
exit 1

- name: Start server
run: |
java -jar conductor-server-boot.jar --server.port=8080 > server.log 2>&1 &
java -jar conductor-server-boot.jar --server.port=8080 \
--conductor.ai.decision.endpoint=http://localhost:9911/v1/systemone \
--conductor.ai.decision.api-key=fake-key \
> server.log 2>&1 &

- name: Wait for server health
run: |
Expand Down Expand Up @@ -155,4 +173,5 @@ jobs:
path: |
results/
server.log
fake-providers.log
retention-days: 14
12 changes: 11 additions & 1 deletion SDK_NEW_LANGUAGE_GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -1337,7 +1337,7 @@ All builders follow the convention: **first argument is always `taskReferenceNam
| `httpPollTask` | `(refName, inputParameters, optional?)` |
| `inlineTask` | `(refName, script, evaluatorType?, optional?)` |
| `subWorkflowTask` | `(refName, workflowName, version?, optional?)` |
| `switchTask` | `(refName, expression, decisionCases?, defaultCase?, optional?)` |
| `switchTask` | `(refName, expression, decisionCases?, defaultCase?, optional?, evaluatorType?)` |
| `forkTask` | `(refName, forkTasks)` |
| `forkTaskJoin` | `(refName, forkTasks, optional?)` → returns `[ForkJoinTask, JoinTask]` |
| `joinTask` | `(refName, joinOn, optional?)` |
Expand Down Expand Up @@ -1465,6 +1465,16 @@ an agents layer, mirror that catalog — e.g.:
| `agents/03-multi-agent.ts` | Multi-agent orchestration |
| `agents/09-human-in-the-loop.ts` | Human-in-the-loop AI |
| `agents/04-mcp-weather.ts` | MCP tool integration |
| `ai-decision-routing.ts` | Synchronous decision SWITCH with inline branches |
| `agents/decision-router.ts` | Decision ToolDef selector routes to chat agents |
| `agents/decision-tool.ts` | Chat agent uses a branchless decision SWITCH tool |

Decision support reuses `switchTask` (sixth argument `evaluatorType: "decision"`; the
expression names the choice question, and `inputParameters` carry model/state/questions)
and `ToolDef` (`toolType: "decision"`). Router tools serialize as
`{name, kind: "decision", model, questions, provider?}` and must have exactly one choice
question whose choices are the sub-agent names; `synthesize: false` skips the final parent
LLM step. No new client methods or builders are required.

#### 7.4 API Journey Examples (9 files)

Expand Down
3 changes: 2 additions & 1 deletion docs/agents/reference/agent-definition.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,8 @@ Key `AgentOptions` fields:
| `tools` | `unknown[]` | `tool()` wrappers, built-in tool defs, framework tools. |
| `agents` | `Agent[]` | Sub-agents (multi-agent). |
| `strategy` | `Strategy` | `'sequential' \| 'parallel' \| 'handoff' \| 'router' \| 'round_robin' \| 'random' \| 'swarm' \| 'manual' \| 'plan_execute'`. |
| `router` | `Agent \| (() => string)` | Required for `strategy: 'router'`. |
| `router` | `Agent \| ToolDef \| (() => string)` | Required for `strategy: 'router'`. A ToolDef must use `toolType: 'decision'` with `config.model` and nonempty `config.questions`; optional `config.provider` is forwarded. |
| `synthesize` | `boolean` | Default `true`. Set `false` to return specialist output without a final LLM synthesis step. |
| `outputType` | Zod schema or JSON Schema | Structured output. |
| `guardrails` | `unknown[]` | Guardrail defs / instances. |
| `handoffs` | `HandoffCondition[]` | `OnTextMention` / `OnToolResult` / `OnCondition`. |
Expand Down
15 changes: 14 additions & 1 deletion docs/agents/reference/agent-schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,18 @@
"description": "The public wire shape emitted by AgentConfigSerializer.serializeAgent() under agentConfig.",
"$ref": "#/$defs/agentConfig",
"$defs": {
"decisionRouter": {
"type": "object",
"required": ["name", "kind", "model", "questions"],
"properties": {
"name": { "type": "string", "minLength": 1 },
"kind": { "const": "decision" },
"model": { "type": "string", "minLength": 1 },
"provider": { "type": "string" },
"questions": { "type": "object", "minProperties": 1 }
},
"additionalProperties": false
},
"taskReference": {
"type": "object",
"required": ["taskName"],
Expand Down Expand Up @@ -52,7 +64,8 @@
"tools": { "type": "array", "items": { "$ref": "#/$defs/tool" } },
"agents": { "type": "array", "items": { "$ref": "#/$defs/agentConfig" } },
"strategy": { "type": "string" },
"router": { "anyOf": [{ "$ref": "#/$defs/taskReference" }, { "$ref": "#/$defs/agentConfig" }] },
"router": { "anyOf": [{ "$ref": "#/$defs/taskReference" }, { "$ref": "#/$defs/agentConfig" }, { "$ref": "#/$defs/decisionRouter" }] },
"synthesize": { "type": "boolean" },
"outputType": {
"type": "object",
"properties": {
Expand Down
5 changes: 5 additions & 0 deletions docs/agents/reference/agent-schema.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,11 @@ recursively via the same function. The published
allowing intentionally open JSON payloads (tool `inputSchema`/`outputSchema`,
`metadata`, guardrail/termination/handoff objects, and per-toolType `config`).

A decision ToolDef in `router` emits `{ name, kind: "decision", model, questions,
provider? }` instead of a nested agent. `model` and nonempty `questions` are required;
an absent provider is omitted. A normal tool emits `toolType: "decision"` with its
config unchanged. `synthesize: false` disables the final specialist synthesis step.

## Framework-passthrough shapes

Two agent kinds bypass the general shape above and emit a minimal
Expand Down
15 changes: 15 additions & 0 deletions docs/api-reference/task-generators.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,21 @@ const task = switchTask(
);
```

The sixth argument selects the evaluator (default `"value-param"`). With
`"javascript"` the expression is a script. With `"decision"` the server runs
decision inference: the expression names the choice question, and the task's
`inputParameters` carry `model`, `state`, `questions`, and an optional
`provider`. See [examples/ai-decision-routing.ts](../../examples/ai-decision-routing.ts).

```typescript
const route = switchTask("route_ref", "route", { billing: [...], technical: [...] }, [], undefined, "decision");
route.inputParameters = {
model: "jev-1.13",
state: "${workflow.input.request}",
questions: { route: { type: "choice", instructions: "...", choices: { billing: "...", technical: "..." } } },
};
```

## Fork-Join Task

_System Task_ - Executes multiple task branches in parallel and waits for all to complete.
Expand Down
96 changes: 96 additions & 0 deletions e2e/fixtures/fake-providers.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@
/* global process, console */
// Deterministic stand-ins for the providers behind Jev decision SWITCHes.
//
// POST /v1/systemone — system-one decision API (conductor.ai.decision.endpoint)
// POST /v1/responses — OpenAI Responses API (conductor.ai.openai.base-url),
// only when FAKE_OPENAI=1; CI uses the real provider.
//
// Decision answers are keyword based: for each choice question, the first
// choice whose key or description shares a word stem with the state wins,
// otherwise the first choice. The fake OpenAI model calls the first function
// tool named in its instructions (or the first tool) once with
// {"state": <last user text>}, then answers with text that echoes the tool
// output. Run: node e2e/fixtures/fake-providers.mjs (PORT, default 9911)
import http from "node:http";

const port = Number(process.env.PORT ?? 9911);
const fakeOpenAI = process.env.FAKE_OPENAI === "1";
const stems = (s) =>
new Set((String(s).toLowerCase().match(/[a-z]+/g) ?? []).filter((w) => w.length > 3).map((w) => w.slice(0, 6)));

function decide(req) {
const state = typeof req.state === "string" ? req.state : JSON.stringify(req.state ?? "");
const stateStems = stems(state);
const answers = {};
for (const [name, q] of Object.entries(req.questions ?? {})) {
if (q.type === "choice") {
const keys = Object.keys(q.criteria ?? {});
const hit = keys.find((k) => [...stems(`${k} ${q.criteria[k]}`)].some((w) => stateStems.has(w)));
answers[name] = { type: "choice", choice: hit ?? keys[0], confidence: 0.9 };
} else if (q.type === "score") {
answers[name] = { type: "score", score: 0, confidence: 0.9 };
} else {
answers[name] = { type: "noul", noul: 0.5, confidence: 0.9 };
}
}
return {
id: `fake-decision-${Date.now()}`,
model: req.model,
answers,
usage: { input_tokens: 42, output_tokens: 1, cost: 0.0001 },
};
}

const textOf = (content) =>
typeof content === "string" ? content : (content ?? []).map((p) => p.text ?? "").join("");

function respond(req) {
const items = typeof req.input === "string" ? [{ type: "message", role: "user", content: req.input }] : req.input ?? [];
const userText = textOf(items.filter((i) => (i.type ?? "message") === "message" && i.role === "user").at(-1)?.content);
const toolOutputs = items.filter((i) => i.type === "function_call_output");
const tools = (req.tools ?? []).filter((t) => t.type === "function");
const base = { id: `fake-resp-${Date.now()}`, object: "response", model: req.model, status: "completed" };
const usage = { input_tokens: 10, output_tokens: 5, total_tokens: 15 };
if (tools.length > 0 && toolOutputs.length === 0) {
const tool = tools.find((t) => (req.instructions ?? "").includes(t.name)) ?? tools[0];
const callId = `call_${Date.now()}`;
return {
...base,
usage,
output: [{ type: "function_call", id: `fc_${callId}`, call_id: callId, name: tool.name, arguments: JSON.stringify({ state: userText }), status: "completed" }],
};
}
const text = toolOutputs.length > 0 ? `FAKE_ANSWER tool=${toolOutputs.at(-1).output}` : `FAKE_ANSWER ${userText}`;
return {
...base,
usage,
output_text: text,
output: [{ type: "message", id: "msg_fake", role: "assistant", status: "completed", content: [{ type: "output_text", text, annotations: [] }] }],
};
}

http
.createServer((req, res) => {
let body = "";
req.on("data", (c) => (body += c));
req.on("end", () => {
let json;
try {
json = JSON.parse(body);
} catch {
res.writeHead(400).end();
return;
}
let out;
if (req.method === "POST" && req.url?.endsWith("/systemone")) out = decide(json);
else if (fakeOpenAI && req.method === "POST" && req.url?.endsWith("/responses")) out = respond(json);
if (!out) {
res.writeHead(404).end();
return;
}
console.log(JSON.stringify({ path: req.url, model: json.model, out: out.answers ?? out.output?.[0]?.type }));
res.writeHead(200, { "content-type": "application/json" });
res.end(JSON.stringify(out));
});
})
.listen(port, () => console.log(`fake providers on :${port} (openai=${fakeOpenAI})`));
Loading
Loading