​

Working with Agents

Agents are the core building blocks in Truffle AI. Each agent is an AI assistant that can be customized for specific tasks or conversations.

​

Creating Agents

Create a new agent using the deployAgent method:

const agent = await truffle.deployAgent({
  name: 'My Assistant',
  instruction: 'You are a helpful AI assistant.',
  model: 'gpt-4o-mini'
});

​

Agent Configuration

The deployAgent method accepts the following parameters:

​

Using Agents

​

Running Tasks

Use the run method to execute one-off tasks:

const result = await agent.run('What is machine learning?');
console.log(result);

​

Chat Sessions

For interactive conversations, use the chat interface:

// Create a chat session
const chat = agent.chat();

// Send messages
const response = await chat.send('Hello!');
console.log(response);

// Access chat history
const history = chat.getHistory();

// Clear chat history
chat.clearHistory();

​

Managing Agents

​

Loading Existing Agents

Load a previously created agent using its ID:

const agent = await truffle.loadAgent('your-agent-id');

​

Updating Agents

Update an agent’s configuration:

await agent.update({
  name: 'New Name',
  instruction: 'Updated instructions'
});

​

Enhancing Agents with RAG

You can enhance your agents with Retrieval Augmented Generation (RAG) to provide them with knowledge from your own documents:

// First, upload a document
const file = /* your file object */;
const uploadResult = await truffle.uploadRAGFile(file);

// Then, update your agent with the document ID
await agent.update({
  documentId: uploadResult.documentId
});

For more details on working with RAG, see the RAG documentation.

​

Deleting Agents

Remove an agent when it’s no longer needed:

await agent.delete();

​

Best Practices

1. Clear Instructions: Provide detailed instructions to shape your agent’s behavior and responses.

2. Context Management: For chat applications, use a single chat session for related conversations to maintain context.

3. Knowledge Enhancement: Use RAG to provide agents with specific knowledge from your documents when they need domain-specific information.

4. Error Handling: Always implement proper error handling:

try {
  const agent = await truffle.deployAgent({
    name: 'My Assistant',
    instruction: 'You are a helpful AI assistant.',
    model: 'gpt-4o-mini'
  });
  
  const result = await agent.run('Hello!');
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Invalid configuration:', error.message);
  } else if (error instanceof AuthenticationError) {
    console.error('Authentication failed:', error.message);
  } else {
    console.error('An error occurred:', error.message);
  }
}

​

Next Steps

Now that you understand how to work with agents, check out our examples to see various use cases and implementation patterns: