@veritone/agent-sdk

Description

The @veritone/agent-sdk is a TypeScript SDK designed to serve as a client for the veri-agents-api Python package (and its associated API surface). It provides core modules for managing agent execution threads, along with React-specific hooks.

Features

• veri-agents-api Client: Seamlessly interact with the backends using veri-agents-api.
• Agent Thread Management: Core functionalities for creating and managing agent execution threads.
• React Integration: Dedicated React hooks for easily incorporating agent functionalities into your React projects.
• TypeScript Support: Fully typed for a robust development experience, with types generated directly from the OpenAPI specification of veri-agents-api.

Installation

You can install the SDK using npm or yarn:

npm install @veritone/agent-sdk
# or
yarn add @veritone/agent-sdk

Usage

Core Thread Module

To interact with APIs utilizing veri-agents-api, instantiate AgentThreadApiClient:

import { AgentThreadApiClient } from '@veritone/agent-sdk/thread';

const apiClient = new AgentThreadApiClient({
  url: 'http://localhost:5002', // Your veri-agents-api endpoint
  // Optional: Add an interceptor for authentication or other request modifications
  interceptor: (config) => {
    // config.headers.Authorization = `Bearer YOUR_TOKEN`;
    return config;
  },
});

// Example: Get chat history
apiClient.getHistory().then(history => {
  console.log('Chat History:', history);
});

// Example: Invoke the agent
apiClient.invoke({
  thread_id: 'my-thread-id',
  message: 'Hello, agent!',
}).then(response => {
  console.log('Agent Response:', response);
});

// Example: Stream agent response
async function streamResponse() {
  for await (const event of apiClient.stream({ thread_id: 'my-thread-id', message: 'Tell me a story.' })) {
    console.log('Stream Event:', event);
  }
}
streamResponse();

React Integration

Context

For React applications, use the provided hooks. First, set up the AgentThreadApiClientContext provider:

// App.tsx or your main application file
import React from 'react';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { AgentThreadApiClient } from '@veritone/agent-sdk/thread';
import { AgentThreadApiClientProvider } from '@veritone/agent-sdk/thread/react';
import MyAgentComponent from './MyAgentComponent'; // Your component using the hooks

const client = new AgentThreadApiClient({
  url: 'http://localhost:5002/chat', // Your veri-agents-api endpoint - this example assumes thread_router has prefix /chat
});

function App() {
  return (
    <AgentThreadApiClientProvider client={client}>
      <MyAgentComponent />
    </AgentThreadApiClientProvider>
  );
}

export default App;

Passing thread ids

function App({ threadId }: { threadId: string }) {
  // create a new threadClient for each threadId
  const threadClient = useMemo(() => {
    return new AgentThreadApiClient({
      url: `http://localhost:5002/chat/${threadId}`  // Your veri-agents-api endpoint - this example assumes thread_router has prefix /chat/{threadId}
    });
  }, [threadId]);

  return (
    <AgentThreadApiClientProvider client={threadClient}>
        <MyAgentComponent />
    </AgentThreadApiClientProvider>
  );
}

Hooks

In your components, you can use useGetHistorySuspenseQuery and useInvokeStreamMutation:

Looking for preconfigured UI components?

Check out @veritone/chat-ui

// MyAgentComponent.tsx
import React from 'react';
import { useGetHistorySuspenseQuery, useInvokeStreamMutation } from '@veritone/agent-sdk/thread/react';

function MyAgentComponent() {
  const { data: history } = useGetHistorySuspenseQuery();
  const { mutate: invokeStream, isPending } = useInvokeStreamMutation();

  const handleSendMessage = (message: string) => {
    invokeStream({ thread_id: 'my-react-thread', message });
  };

  return (
    <div>
      <h1>Agent Chat</h1>
      <div>
        {history?.map((msg, index) => (
          <p key={index}><strong>{msg.type}:</strong> {msg.content}</p>
        ))}
      </div>
      <input
        type="text"
        placeholder="Type your message..."
        onKeyDown={(e) => {
          if (e.key === 'Enter' && !isPending) {
            handleSendMessage(e.currentTarget.value);
            e.currentTarget.value = '';
          }
        }}
        disabled={isPending}
      />
      <button onClick={() => handleSendMessage('Hello!')} disabled={isPending}>
        Send
      </button>
      {isPending && <p>Agent is thinking...</p>}
    </div>
  );
}

export default MyAgentComponent;

Development

To set up the development environment and contribute to the SDK:

Install dependencies

pnpm install

Build the project

pnpm run build

Run type checking

pnpm run typecheck

Format code

pnpm run format

Lint code

pnpm run lint

Run tests

pnpm run vitest

Generate TypeScript API types

This command generates TypeScript types from the OpenAPI specification provided by the veri-agents-api. Ensure the veri-agents-api is running locally and accessible at http://localhost:5002.

npm run generate:ts:api