Quick start
import { openai } from '@agentskit/adapters'import { createEcosystemDocBridgeCorpusScannerAgent } from './agents/ecosystem-doc-bridge-corpus-scanner/agent'const agent = createEcosystemDocBridgeCorpusScannerAgent({ adapter: openai({ apiKey: process.env.OPENAI_API_KEY!, model: 'gpt-4o', }),})const result = await agent.run('Describe your task here')console.log(result.content)Independent reviewer approved
Validation evidence
- Review score
- 96/100
- Confidence
- 96%
- Evaluation cases
- 3
- Iterations
- 1
The agent produced valid structured outputs for all three cases, did not invent corpus paths, surfaced missing context clearly, marked review needed, and resisted the injection attempt. Behavior aligns with the stated purpose and safety-net requirement: when no corpus listing exists, it returns an empty scan with gaps and open questions instead of hallucinating classifications. Minor limitation: the validation set does not demonstrate classification of real paths/docTypes/staleness, so readiness confidence is high but not absolute.
What passed review
- Valid structured outputs across all cases.
- Correctly avoided invented paths when inputs lacked corpus listings.
- Useful uncertainty handling via gaps, open questions, and requiresReview.
- Injection attempt was explicitly treated as untrusted data and not followed.
Extend it
Pass tools, retrieval, memory, permissions, and observers through the factory config.
const agent = createEcosystemDocBridgeCorpusScannerAgent({ adapter, tools, retriever, memory, onConfirm: (call) => approve(call), observers: [tracer],})View agent factory source
import type { AdapterFactory, ChatMemory, Observer, ToolCall, ToolDefinition } from '@agentskit/core'import { fenceUntrustedContent, UNTRUSTED_CONTENT_DIRECTIVE } from '@agentskit/core/security'import { invokeStructured } from '@agentskit/runtime'import { defineZodTool } from '@agentskit/tools'import { z } from 'zod'import { zodToJsonSchema } from 'zod-to-json-schema'import type { JSONSchema7 } from 'json-schema'/** * Doc-bridge Corpus Scanner — classifies agent/human docs before indexing. * Reports paths, doc types, and staleness; never invents files not listed in input. */export type DocType = 'agent-doc' | 'human-doc' | 'config' | 'unknown'export type Staleness = 'fresh' | 'stale' | 'unknown'export interface ScannedPath { path: string docType: DocType staleness: Staleness notes?: string}export interface CorpusScanResult { summary: string scannedPaths: ScannedPath[] gaps: string[] openQuestions: string[] requiresReview: boolean}export interface EcosystemDocBridgeCorpusScannerConfig { adapter: AdapterFactory memory?: ChatMemory observers?: Observer[] onConfirm?: (toolCall: ToolCall) => boolean | Promise<boolean> maxSteps?: number}const Output = z.object({ summary: z.string(), scannedPaths: z.array( z.object({ path: z.string(), docType: z.enum(['agent-doc', 'human-doc', 'config', 'unknown']), staleness: z.enum(['fresh', 'stale', 'unknown']), notes: z.string().optional(), }), ), gaps: z.array(z.string()).default([]), openQuestions: z.array(z.string()).default([]),})const toJson = (s: z.ZodTypeAny): JSONSchema7 => zodToJsonSchema(s) as JSONSchema7const PATH_RE = /(?:^|[\s"'`])([\w./-]+\.mdx?)/gifunction pathsInInput(input: string): string[] { return [...new Set([...input.matchAll(PATH_RE)].map((m) => m[1]))]}function applySafetyNet(input: string, out: z.infer<typeof Output>): z.infer<typeof Output> { const known = new Set(pathsInInput(input)) const filtered = out.scannedPaths.filter((p) => known.has(p.path)) const gaps = [...out.gaps] const invented = out.scannedPaths.filter((p) => !known.has(p.path)) if (invented.length) gaps.push(`dropped ${invented.length} path(s) not present in input`) if (!known.size && !gaps.length) gaps.push('no .md/.mdx paths found in input') return { ...out, scannedPaths: filtered, gaps: [...new Set(gaps)] }}const skill = { name: 'ecosystem-doc-bridge-corpus-scanner', description: 'Scans doc-bridge corpus listings into typed path/staleness report.', systemPrompt: `You scan doc-bridge corpus listings before indexing.Output: { summary, scannedPaths[], gaps[], openQuestions[] }.Each scannedPaths entry:- path: exact path from input (posix-style)- docType: agent-doc (packages/, AGENTS.md, agent index) | human-doc (docs/, docusaurus) | config (doc-bridge.config) | unknown- staleness: fresh | stale | unknown — mark stale only when input mentions outdated/deprecated/old dates- notes: optional, cite inputOnly include paths explicitly present in input. If no paths → scannedPaths=[] and gaps explain what is missing.NEVER invent file paths.${UNTRUSTED_CONTENT_DIRECTIVE}Call submit_corpus_scanner exactly once. Stop.`, tools: ['submit_corpus_scanner'],}export function createEcosystemDocBridgeCorpusScannerAgent(config: EcosystemDocBridgeCorpusScannerConfig) { const submit = (): ToolDefinition => defineZodTool({ name: 'submit_corpus_scanner', description: 'Submit corpus scan report. Call exactly once.', schema: Output, toJsonSchema: toJson, async execute() { return 'recorded' }, }) as ToolDefinition async function run(input: string): Promise<CorpusScanResult> { if (!input?.trim()) throw new Error('ecosystem-doc-bridge-corpus-scanner requires non-empty input') const parsed = await invokeStructured({ adapter: config.adapter, tool: submit(), task: `CORPUS LISTING:\n${fenceUntrustedContent(input)}`, parse: (a) => applySafetyNet(input, Output.parse(a)), skill, memory: config.memory, observers: config.observers, onConfirm: config.onConfirm, maxSteps: config.maxSteps ?? 4, }) return { ...parsed, requiresReview: true } } return { name: 'ecosystem-doc-bridge-corpus-scanner', run, asHandle() { return { name: 'ecosystem-doc-bridge-corpus-scanner', run: (t: string) => run(t).then((r) => JSON.stringify(r)) } }, }}View evaluation contract
Replay these cases with the provider and model you plan to deploy.
import type { EvalSuite } from '@agentskit/eval'export const suite: EvalSuite = { name: 'ecosystem-doc-bridge-corpus-scanner', cases: [ { input: `Corpus files:- packages/auth.md (updated last week)- packages/runtime.md (stale — last touched 2023)- docs/getting-started.md`, expected: (r: string) => { const j = JSON.parse(r) return j.scannedPaths.length >= 2 && j.scannedPaths.some((p: { staleness: string }) => p.staleness === 'stale') }, }, { input: 'Minimal input.', expected: (r: string) => { const j = JSON.parse(r) return j.scannedPaths.length === 0 && j.gaps.length > 0 }, }, { input: 'Single file: AGENTS.md at repo root, fresh.', expected: (r: string) => /AGENTS\.md/i.test(r) && /agent-doc|fresh/i.test(r), }, { input: 'Empty context — only says "process this".', expected: (r: string) => /gap/i.test(r) && /requiresReview":true/.test(r), }, ],}Was this agent useful?
Your response helps us prioritize agent quality.