51-shared-state.ts

/**
 * 51 - Shared State — tools sharing state across calls via ToolContext.
 *
 * Tools can read and write to `context.state`, a dictionary that persists
 * across all tool calls within the same agent execution.
 *
 * Requirements:
 *   - Conductor server with state support
 *   - AGENTSPAN_SERVER_URL=http://localhost:8080/api as environment variable
 *   - AGENTSPAN_LLM_MODEL=openai/gpt-4o-mini as environment variable
 */

import { Agent, AgentRuntime, tool } from '@io-orkes/conductor-javascript/agents';
import type { ToolContext } from '@io-orkes/conductor-javascript/agents';
import { llmModel } from './settings';

// -- Tools -------------------------------------------------------------------

const addItem = tool(
  async (args: { item: string }, context?: ToolContext) => {
    const items = (context?.state?.shopping_list as string[] | undefined) ?? [];
    items.push(args.item);
    if (context?.state) {
      context.state.shopping_list = items;
    }
    return { added: args.item, total_items: items.length };
  },
  {
    name: 'add_item',
    description: 'Add an item to the shared shopping list.',
    inputSchema: {
      type: 'object',
      properties: {
        item: { type: 'string', description: 'The item to add' },
      },
      required: ['item'],
    },
  },
);

const getList = tool(
  async (_args: Record<string, never>, context?: ToolContext) => {
    const items = (context?.state?.shopping_list as string[] | undefined) ?? [];
    return { items, total_items: items.length };
  },
  {
    name: 'get_list',
    description: 'Get the current shopping list from shared state.',
    inputSchema: {
      type: 'object',
      properties: {
      },
    },
  },
);

const clearList = tool(
  async (_args: Record<string, never>, context?: ToolContext) => {
    if (context?.state) {
      context.state.shopping_list = [];
    }
    return { status: 'cleared' };
  },
  {
    name: 'clear_list',
    description: 'Clear the shopping list.',
    inputSchema: {
      type: 'object',
      properties: {
      },
    },
  },
);

// -- Agent -------------------------------------------------------------------

export const agent = new Agent({
  name: 'shopping_assistant_51',
  model: llmModel,
  instructions:
    'You help manage a shopping list. Use add_item to add items, ' +
    'get_list to view the list, and clear_list to reset it. ' +
    'IMPORTANT: Always add all items first, then call get_list separately ' +
    'in a follow-up step to verify the list contents. Never call get_list ' +
    'in the same batch as add_item calls.',
  tools: [addItem, getList, clearList],
});

// -- Run ---------------------------------------------------------------------

async function main() {
  const runtime = new AgentRuntime();
  try {
    const result = await runtime.run(
    agent,
    'Add milk, eggs, and bread to my shopping list, then show me the list.',
    );
    result.printResult();

    // Production pattern:
    // 1. Deploy once during CI/CD (optional -- serve() below also deploys):
    // await runtime.deploy(agent);
    // CLI alternative:
    // agentspan deploy --package sdk/typescript/examples --agents shopping_assistant_51
    //
    // 2. In a separate long-lived worker process (deploys + registers workers + starts polling):
    // await runtime.serve(agent);
  } finally {
    await runtime.shutdown();
  }
}

main().catch(console.error);