Example Projects & Walk-throughs

import { agentic } from '@symbolica/agentica';
import { WebClient } from '@slack/web-api';

const SLACK_BOT_TOKEN = 'YOUR-TOKEN-HERE';
// Initialize Slack client
const slackClient = new WebClient(SLACK_BOT_TOKEN);

/** Post message
 * @param userName The name of the user to send a morning message to
 */
async function postMessage(userName: string, text: string): Promise<void> {
    await slackClient.chat.postMessage({
        channel: `@${userName}`,
        text: text,
    });
}

/**
 * Uses the Slack API to send the user a direct message. Light and cheerful!
 * @param userName The name of the user to send a morning message to
 */
async function sendMorningMessage(userName: string): Promise<void> {
    await agentic<void>('Use the Slack API to send the user a direct message. Light and cheerful!', {
        postMessage,
        userName,
    });
}

// Execute the function
void sendMorningMessage('John Smith');

/**
 * Deep Research Demo - Multi-agent research with web search and citations.
 */

import * as fs from 'fs';
import * as path from 'path';
import { randomUUID } from 'crypto';

import { Agent, spawn } from '@symbolica/agentica';
import { ExaAdmin, ExaClient, SearchResult } from '@symbolica/agentica/std/web';
import { mdToPdf } from 'md-to-pdf';
import { exit } from 'process';

type SourceType = 'primary' | 'secondary' | 'vendor' | 'press' | 'blog' | 'forum' | 'unknown';

const LEAD_RESEARCHER_MODEL = 'anthropic:claude-opus-4.5';
const SUBAGENT_MODEL = 'anthropic:claude-sonnet-4.5';
const CITATION_MODEL = 'openai:gpt-4.1';

const CITATION_PREMISE = `
You are a citation agent.

# Task
You must:
1. Review the research report provided to you as \`research_report\` line by line.
2. Identify which lines of the research report use information that could be from web search results.
3. List the web search results that were used in creating the research report.
4. For each of these lines, use the \`loadSearchResult\` function to load the web search result that was used.
5. Add a markdown citation with the URL of the web search result to the claim in the research report by modifying the \`research_report\` variable.
6. Once this is done, make sure the \`research_report\` is valid markdown - if not, change the markdown to make it valid.
7. Use the \`saveReport\` function to save the research report to memory as a markdown file at the end.
8. Return saying you have finished.

# Rules
- Your citations MUST be consistent throughout the \`research_report\`.
- Any URL in the final markdown MUST be formatted as a markdown link, not a bare URL.
- You MUST use the \`listSearchResults\` function to list the web search results that were used in creating the research report
- You MUST use the \`loadSearchResult\` function to load the web search results.
- You MUST use the \`research_report\` variable provided to you to modify the research report by adding citations.
- You MUST make sure the \`research_report\` is valid markdown.
- You MUST use the \`saveReport\` function to save the research report to memory at the end.
- You MUST inspect the report before saving it to make sure it is valid and what you intended. Iterate until it is valid.

## Citation format
- Prefer inline citations like: \`... claim ... ([source](https://example.com))\`
- If multiple sources support a sentence, include multiple links: \`... ([s1](...), [s2](...))\`
`;

const LEAD_RESEARCHER_PREMISE = `
You are a lead researcher. You have access to web-search enabled subagents.

# Task
You must:
1. Create a plan to research the user query.
2. Determine how many specialised subagents (with access to the web) are necessary, each with a different specific research task.
3. Call ALL subagents in parallel. In the Python REPL, use \`asyncio.gather(..., return_exceptions=True)\` so partial results are preserved.
4. Summarise the results of the subagents in a final research report as markdown. Use sections, sub-sections, list and formatting to make the report easy to read and understand. The formatting should be consistent and easy to follow.
5. Check the final research report, as this will be shown to the user.
6. Return the final research report using \`return\` at the very end.

# Rules
- Do NOT construct the final report until you have run the subagents.
- Do NOT return the final report in the REPL until planning, assigning subagents and returning the final report is complete.
- Do NOT add citations to the final research report yourself, this will be done afterwards.
- Do NOT repeat yourself in the final research report.
- You MUST raise an Error if you cannot complete the task with what you have available.
- You MUST check the final research report string before returning it to the user.

## Planning
- You MUST write the plan yourself.
- You MUST write the plan before assigning subagents to tasks.
- You MUST break down the task into small individual tasks.

## Subagents
- You MUST assign each small individual task to a subagent.
- You MUST NOT assign multiple unrelated tasks to the same subagent.
- You MUST instruct subagents to use the webSearch and saveSearchResult functions if the task requires it.
- Do NOT ask subagents to cite the web, instead instruct them to use the saveSearchResult function.
- Subagents MUST be assigned independent tasks.
- IF after subagents have returned their findings more research is needed, you can assign more subagents to tasks.
- DO NOT try to pre-emptively *parse* the output of the subagents, **just look at the output yourself**.
- Subagents may fail! In the Python REPL, use \`asyncio.gather(..., return_exceptions=True)\` to not lose successful results.

## Final Report
- Do NOT write the final report yourself without running subagents to do so.
- Do NOT add citations to the final research report yourself, this will be done afterwards by another agent.
- Do NOT repeat yourself in the final research report.
- Do NOT return a report with missing information, omitted fields or \`N/A\` values. If more work needs to be done, you must assign more subagents to tasks, or reuse the necessary subagents to extract more information.
- You MUST load the plan from memory before returning the final research report to check that you have followed the plan.
- You MUST check the final research report before returning it to the user.
- Check the final report for quality, completeness and consistency. If up to standard, return using a single \`return\` as the sole statement in its very own
- Your final report MUST include a short "Sources consulted" section:
  - List each source URL you relied on
  - Include its sourceType and 1-2 extracted claims
- Any URL you include MUST be a markdown hyperlink (not a bare URL).
`;

const SUBAGENT_PREMISE = `
You are a helpful assistant.

# Task
You must:
1. Construct a list of things to search for using the webSearch function.
2. In REPL, execute ALL webSearch calls in parallel using \`asyncio.gather(...)\` (use \`asyncio.run(...)\` if needed).
3. For each search result, use \`print()\` to print relevant sections via SearchResult.contentWithLineNumbers(start, end).
4. Identify which lines of content you are going to use in your report.
5. Use the saveSearchResult function to save the SearchResult to memory and include the lines of the content that you have used.
   - Include the specific \`query\` you searched for.
   - Include \`extractedClaims\`: a list of short claims you will rely on (derived from the saved lines).
   - Include \`sourceType\`: one of ["primary", "secondary", "vendor", "press", "blog", "forum", "unknown"].
     Use your best judgment based on the URL/domain and the content.
   - IMPORTANT: saveSearchResult returns a saved artifact path; keep it and include it in sources[].artifactPath
6. Condense the search results into a single report with what you have found.
7. Return the report using \`return\` at the very end in a separate REPL session.

# Rules
- You MUST use \`print()\` to print the content of each search result via SearchResult.contentWithLineNumbers(start, end).
- You MUST use the webSearch function if instructed to do so OR if the task requires finding information.
- Do NOT assume that the webSearch function will return the information you need, you must go through the content of each search result line by line by combing through the content with SearchResult.contentWithLineNumbers(start, end).
- Do NOT assume which lines of content you are going to use in your report, you must go through the content of each search result line by line via SearchResult.contentWithLineNumbers(start, end).
- If you cannot find any information, do NOT provide information yourself, instead raise an error for the lead researcher in the REPL.
- You MUST save the SearchResult of any research that you have used to memory and include the lines of the content that you have used (are relevant).
- When saving, pass \`query\`, \`extractedClaims\`, and \`sourceType\` to saveSearchResult.
- Your returned SubAgentReport MUST include \`sources\`: one entry per saved source, including url, sourceType, query, extractedClaims, artifactPath, and linesUsed.
- Return the report using \`return\` at the very end in a separate REPL session.
`;

const STORAGE_DIR = 'deep_research_test';

/**
 * Centralized storage for all research artifacts.
 */
class Storage {
    private readonly directory = STORAGE_DIR;
    private resultCounts: Map<number, number> = new Map();

    constructor() {
        fs.mkdirSync(this.directory, { recursive: true });
    }

    // Plan

    /**
     * Save the research plan.
     */
    savePlan(plan: string): void {
        fs.writeFileSync(path.join(this.directory, 'plan.md'), plan);
        console.log(`[storage] saved plan.md (${plan.length} chars)`);
    }

    /**
     * Load the research plan.
     */
    loadPlan(): string {
        const planPath = path.join(this.directory, 'plan.md');
        if (!fs.existsSync(planPath)) {
            throw new Error('Plan file not created yet.');
        }
        return fs.readFileSync(planPath, 'utf-8');
    }

    // Search Results

    /**
     * Tool storage: persist the *used* slices of a SearchResult as a JSON artifact.
     *
     * The returned file is later consumed by the citation agent via `loadSearchResult()`.
     *
     * - `linesUsed` is 1-indexed inclusive ranges into `result.contentLines`.
     * - `meta` is optional but helps trace provenance (query, claims, source quality).
     */
    saveSearchResult(
        subagentId: number,
        result: SearchResult,
        linesUsed: Array<[number, number]>,
        meta?: {
            // With `exactOptionalPropertyTypes`, passing `{ query: undefined }` is not
            // assignable to `{ query?: string }`. Allow explicit `undefined` so
            // subagents can pass optional args positionally without extra boilerplate.
            query?: string | undefined;
            extractedClaims?: string[] | undefined;
            sourceType?: SourceType | undefined;
            sourceNotes?: string | undefined;
        }
    ): string {
        const count = (this.resultCounts.get(subagentId) ?? 0) + 1;
        this.resultCounts.set(subagentId, count);

        const subagentDir = path.join(this.directory, `subagent_${subagentId}`);
        fs.mkdirSync(subagentDir, { recursive: true });

        const filePath = path.join(subagentDir, `result_${count}.json`);

        // Extract only the relevant lines
        const filteredLines: string[] = [];
        for (const [start, end] of linesUsed) {
            filteredLines.push(...result.contentLines.slice(start - 1, end));
        }

        const data = {
            title: result.title,
            url: result.url,
            content_lines: filteredLines,
            score: result.score,
            // Rich artifact metadata (kept compatible with SearchResult.fromJSON/load in citation flows).
            saved_at: new Date().toISOString(),
            subagent_id: subagentId,
            query: meta?.query ?? null,
            lines_used: linesUsed,
            extractedClaims: meta?.extractedClaims ?? [],
            sourceType: meta?.sourceType ?? null,
            sourceNotes: meta?.sourceNotes ?? null,
        };
        fs.writeFileSync(filePath, JSON.stringify(data));
        console.log(`[storage] saved search artifact: ${filePath} (${result.url})`);
        return filePath;
    }

    loadSearchResult(filePath: string): SearchResult {
        /**
         * Load a previously saved JSON artifact and return it as a SearchResult.
         *
         * Note: artifacts may include extra metadata fields, but the SearchResult
         * payload is reconstructed from the core fields.
         */
        const resolvedPath = path.resolve(filePath);
        if (!resolvedPath.startsWith(path.resolve(this.directory))) {
            throw new Error(`Path must be within ${this.directory}`);
        }
        const data = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
        return new SearchResult({
            title: data.title,
            url: data.url,
            contentLines: data.content_lines,
            score: data.score,
        });
    }

    /**
     * List all saved search result paths.
     */
    listSearchResults(): string[] {
        const files: string[] = [];
        const entries = fs.readdirSync(this.directory, { withFileTypes: true });

        for (const entry of entries) {
            if (entry.isDirectory() && entry.name.startsWith('subagent_')) {
                const subagentDir = path.join(this.directory, entry.name);
                const subFiles = fs.readdirSync(subagentDir);
                for (const file of subFiles) {
                    if (file.endsWith('.json') && /^result_\d+\.json$/.test(file)) {
                        files.push(path.join(subagentDir, file));
                    }
                }
            }
        }
        return files;
    }

    // Report

    /**
     * Save the final report as markdown and PDF.
     */
    async saveReport(mdReport: string): Promise<string> {
        const mdPath = path.join(this.directory, 'report.md');
        const pdfPath = path.join(this.directory, 'report.pdf');

        fs.writeFileSync(mdPath, mdReport);
        console.log(`[storage] saved report.md (${mdReport.length} chars)`);

        try {
            const pdf = await mdToPdf({ content: mdReport });
            if (pdf.content) {
                fs.writeFileSync(pdfPath, pdf.content);
                console.log(`[storage] saved report.pdf (${pdf.content.length} bytes)`);
            }
        } catch (e) {
            console.warn(`Warning: PDF conversion failed: ${e}`);
        }

        return pdfPath;
    }

    get reportPath(): string {
        return path.join(this.directory, 'report.pdf');
    }

    reportExists(): boolean {
        return fs.existsSync(path.join(this.directory, 'report.md'));
    }

    // Summary

    /**
     * Return a summary of all stored artifacts.
     */
    summary(): string {
        const lines = [
            '',
            '━'.repeat(40),
            `📁 Research stored in: ${path.resolve(this.directory)}`,
            '━'.repeat(40),
        ];

        if (this.reportExists()) {
            lines.push(`📄 Report:  report.pdf`);
            lines.push(`           report.md`);
        }

        if (fs.existsSync(path.join(this.directory, 'plan.md'))) {
            lines.push('📋 Plan:    plan.md');
        }

        const searchResults = this.listSearchResults();
        if (searchResults.length > 0) {
            lines.push(`🔍 Search results: ${searchResults.length} files`);
            const bySubagent: Map<string, string[]> = new Map();
            for (const filePath of searchResults) {
                const subagent = path.basename(path.dirname(filePath));
                if (!bySubagent.has(subagent)) bySubagent.set(subagent, []);
                bySubagent.get(subagent)!.push(path.basename(filePath));
            }
            for (const [subagent, files] of [...bySubagent.entries()].sort()) {
                lines.push(`           ${subagent}/: ${files.length} results`);
            }
        }

        lines.push('━'.repeat(40));
        return lines.join('\n');
    }
}

const storage = new Storage();

/**
 * The title, relevant URLs and relevant content from one search session.
 * The content can be paraphrased or summarised, but
 * - MUST be consistent with the original content from; and
 * - MUST be derived from the **lines used** in the search result.
 */
interface SubAgentReport {
    /**
     * Structured output of a web-search subagent.
     *
     * `sources` is intended for the lead agent to quickly inspect provenance/quality
     * without reloading artifacts.
     */
    title: string;
    content: string;
    sources: Array<{
        /** Source URL. */
        url: string;
        /** Coarse source label (primary/secondary/vendor/press/blog/forum/unknown). */
        sourceType?: SourceType;
        /** Query used to discover this source (if provided). */
        query?: string;
        /** Short claims derived from the cited lines that the subagent relied on. */
        extractedClaims: string[];
        /** Saved artifact path (within storage directory). */
        artifactPath?: string;
        /** 1-indexed inclusive line ranges into the saved artifact's content. */
        linesUsed?: Array<[number, number]>;
    }>;
}

let subagentCounter = 0;

/**
 * A subagent with web search capabilities.
 * For each task, a subagent must be **created**, then **run** with `.call()`.
 * If a subagent needs to be reused, perhaps because it got something wrong, it
 * may be run **again** with a second `.call()`, persisting its history.
 */
class SubAgent {
    private id: number = 0;
    private exa: ExaClient | null = null;
    private agent: Agent | null = null;
    private initialized = false;

    async ensureInit(): Promise<void> {
        if (this.initialized) return;
        this.initialized = true;

        this.id = ++subagentCounter;
        console.log(`[subagent ${this.id}] initializing`);

        // Create ephemeral Exa API key for this subagent
        const admin = new ExaAdmin();
        const keyName = `SubAgent_${this.id}_${randomUUID()}`;
        const apiKey = await admin.createKey(keyName);
        console.log(`Created Exa API key for subagent ${this.id}: ${apiKey.slice(0, 4)}...${apiKey.slice(-4)}`);

        this.exa = new ExaClient({ apiKey });

        // Create scope with web search functions
        /**
         * Tool: search the web for `query`. Returns a small list of SearchResult objects.
         */
        const webSearch = async (query: string): Promise<SearchResult[]> => {
            console.log(`Searching: ${query}`);
            return await this.exa!.search(query, { numResults: 2 });
        };

        /**
         * Tool: save a SearchResult artifact for later citation/inspection.
         *
         * - `linesUsed`: 1-indexed inclusive ranges into `result.contentLines`
         * - `query` / `extractedClaims` / `sourceType` are optional provenance/quality metadata
         *
         * Returns the file path of the saved artifact.
         */
        const saveSearchResult = (
            result: SearchResult,
            linesUsed: Array<[number, number]>,
            query?: string,
            extractedClaims?: string[],
            sourceType?: SourceType,
            sourceNotes?: string
        ): string => {
            return storage.saveSearchResult(this.id, result, linesUsed, { query, extractedClaims, sourceType, sourceNotes });
        };

        this.agent = await spawn(
            {
                model: SUBAGENT_MODEL,
                premise: SUBAGENT_PREMISE,
            },
            {
                webSearch,
                saveSearchResult,
                SearchResult,
            }
        );
        console.log(`[subagent ${this.id}] ready`);
    }

    /**
     * Run the subagent on a task.
     */
    async call(task: string): Promise<SubAgentReport> {
        await this.ensureInit();
        console.log(`Running web-search subagent (${this.id})`);
        const result = await this.agent!.call<SubAgentReport>(task);
        console.log(`[subagent ${this.id}] finished: ${JSON.stringify(result.title)}`);
        return result;
    }
}

/**
 * Get a web-search enabled subagent to run a task for you.
 * @param task - The task assigned to the subagent.
 * @returns The report from the subagent.
 */
async function runSubAgent(task: string): Promise<SubAgentReport> {
    const subAgent = new SubAgent();
    return await subAgent.call(task);
}

/**
 * Agent that adds citations to a research report.
 */
class CitationAgent {
    private agent: Agent | null = null;
    private initialized = false;

    async ensureInit(): Promise<void> {
        if (this.initialized) return;
        this.initialized = true;

        this.agent = await spawn(
            {
                model: CITATION_MODEL,
                premise: CITATION_PREMISE,
            },
            {
                /** Tool: list all saved search-result artifact paths. */
                listSearchResults: () => storage.listSearchResults(),
                /** Tool: load a saved search-result artifact and return a SearchResult. */
                loadSearchResult: (p: string) => storage.loadSearchResult(p),
                /** Tool: persist the final report (md + pdf). */
                saveReport: (md: string) => storage.saveReport(md),
            }
        );
    }

    /**
     * Add citations to a research report.
     */
    async call(mdReport: string): Promise<void> {
        console.log('Running citation agent');
        await this.ensureInit();
        console.log(`[citation] adding citations to report (${mdReport.length} chars)`);
        await this.agent!.call<void>(
            `The \`research_report = ${mdReport.slice(0, 10)}...[truncated]\` has been provided to you in the REPL.`,
            { research_report: mdReport }
        );
        console.log('[citation] done');
    }
}

/**
 * Orchestrates a deep research session with multiple agents.
 */
class DeepResearchSession {
    private leadResearcher: Agent | null = null;
    private citationAgent = new CitationAgent();
    private initialized = false;

    private async ensureInit(): Promise<void> {
        if (this.initialized) return;
        this.initialized = true;

        console.log('[session] initializing lead researcher');

        this.leadResearcher = await spawn(
            {
                model: LEAD_RESEARCHER_MODEL,
                premise: LEAD_RESEARCHER_PREMISE,
            },
            {
                savePlan: (plan: string) => storage.savePlan(plan),
                loadPlan: () => storage.loadPlan(),
                listSearchResults: () => storage.listSearchResults(),
                loadSearchResult: (p: string) => storage.loadSearchResult(p),
                runSubAgent,
            }
        );
        console.log('[session] lead researcher ready');

        await this.citationAgent.ensureInit();
        console.log('[session] citation agent ready');
    }

    /**
     * Run the deep research process.
     */
    async call(query: string): Promise<string> {
        await this.ensureInit();

        try {
            console.log(`[session] starting research: ${JSON.stringify(query.slice(0, 120))}${query.length > 120 ? '…' : ''}`);
            // Research phase
            const report = await this.leadResearcher!.call<string>(query);
            console.log(`[session] research draft ready (${report.length} chars)`);

            // Citation phase
            await this.citationAgent.call(report);

            if (!storage.reportExists()) {
                throw new Error('Report was not created');
            }

            console.log(storage.summary());

            return `Check out the research report at ${storage.reportPath}. Ask me any questions!`;
        } finally {
            // Clean up ephemeral API keys
            console.log('Pruning Exa API keys...');
            const deleted = await new ExaAdmin().pruneKeys('SubAgent_');
            if (deleted > 0) {
                console.log(`Pruned ${deleted} key(s)`);
            }
            console.log('[session] done');
        }
    }
}

async function main() {
    const session = new DeepResearchSession();
    const result = await session.call(
        'What are all of the companies in the US working on AI agents in 2025? ' +
            'Make a list of at least 10. For each, include the name, website and product, ' +
            'description of what they do, type of agents they build, and their vertical/industry.'
    );
    console.log(result);
    exit(0);
}

main().catch(console.error);