> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.athenaintel.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.athenaintel.com/_mcp/server.

# Build with Agents

> Use the General Agent to perform long-running tasks with tool use.

This example shows how to use the General Agent with tools for research, browsing, and multi-step conversations. The General Agent is the default agent in [Spaces](https://resources.athenaintel.com/docs/applications/spaces).

Key features:

* Use prebuilt tools like web browsing and search
* Full TypeScript support with type safety
* Support for multi-step conversations
* Custom system prompts for specialized behavior

### Install Package

#### pnpm

```bash
pnpm add @athenaintel/sdk
```

#### bun

```bash
bun add @athenaintel/sdk
```

#### yarn

```bash
yarn add @athenaintel/sdk
```

#### npm

```bash
npm install @athenaintel/sdk
```

### Set Up Client

```typescript
import type { AthenaIntelligence } from '@athenaintel/sdk';
import { AthenaIntelligenceClient } from '@athenaintel/sdk';

// Basic client setup (uses default production API)
const client = new AthenaIntelligenceClient({
  apiKey: process.env.ATHENA_API_KEY,
});

// Override baseUrl for custom API endpoints
const customClient = new AthenaIntelligenceClient({
  apiKey: process.env.ATHENA_API_KEY,
  baseUrl: 'https://your-custom-api.example.com', // Custom API endpoint
});
```

### Basic Agent Usage

Start with a simple search request to understand the basic pattern:

```typescript
const request: AthenaIntelligence.GeneralAgentRequest = {
  config: {
    enabled_tools: ['search'],
    model: 'gpt-4-turbo-preview',
  },
  messages: [
    {
      content: 'Search for information about Athena Intelligence and summarize what you find.',
      role: 'user',
      type: 'user',
    },
  ],
};

const response = await client.agents.general.invoke(request);
console.log('Response received:', JSON.stringify(response, null, 2));
```

### Multi-Tool Workflows

Combine multiple tools with custom system prompts for more sophisticated tasks:

```typescript
const multiToolRequest: AthenaIntelligence.GeneralAgentRequest = {
  config: {
    enabled_tools: ['search', 'browse'],
    system_prompt: 'You are a helpful research assistant. Use search and browse tools to find comprehensive information.',
    model: 'gpt-4-turbo-preview',
  },
  messages: [
    {
      content: 'Research the latest developments in AI and provide a detailed summary with sources.',
      role: 'user',
      type: 'user',
    },
  ],
};

const multiToolResponse = await client.agents.general.invoke(multiToolRequest);
console.log('Multi-tool response:', JSON.stringify(multiToolResponse, null, 2));
```

### Maintain Conversation Context

Build multi-turn conversations by maintaining the message history:

```typescript
// Start with system message and initial user question
const messages: AthenaIntelligence.InputMessage[] = [
  {
    content: 'You are a knowledgeable assistant specializing in technology and business analysis.',
    role: 'system',
    type: 'system',
  },
  {
    content: 'What are the key trends in artificial intelligence for 2024?',
    role: 'user',
    type: 'user',
  },
];

const config: AthenaIntelligence.GeneralAgentConfig = {
  enabled_tools: ['search'],
  model: 'gpt-4-turbo-preview',
};

// First request
let conversationRequest: AthenaIntelligence.GeneralAgentRequest = {
  config,
  messages,
};

const firstResponse = await client.agents.general.invoke(conversationRequest);
console.log('First response received');

// Add the assistant's response to conversation history
if (firstResponse.messages && firstResponse.messages.length > 0) {
  const lastMessage = firstResponse.messages[firstResponse.messages.length - 1];
  messages.push({
    content: lastMessage.kwargs?.content || 'No content',
    role: 'assistant',
    type: 'assistant',
  });
}

// Add follow-up question
messages.push({
  content: 'Can you provide more specific examples of companies implementing these trends?',
  role: 'user',
  type: 'user',
});

// Continue conversation with full context
conversationRequest = {
  config,
  messages,
};

const secondResponse = await client.agents.general.invoke(conversationRequest);
console.log('Conversation completed:', JSON.stringify(secondResponse, null, 2));
```

### Error Handling

Always include proper error handling for production applications:

```typescript
import { AthenaIntelligenceError } from '@athenaintel/sdk';

try {
  const response = await client.agents.general.invoke(request);
  console.log('Response received:', response);
} catch (error) {
  if (error instanceof AthenaIntelligenceError) {
    console.error(`Athena API error (${error.statusCode}): ${error.message}`);
  } else {
    console.error('Unexpected error:', error);
  }
}
```

### Complete Example

Here's a complete working example that demonstrates all the concepts:

```typescript
import type { AthenaIntelligence } from '@athenaintel/sdk';
import { AthenaIntelligenceClient, AthenaIntelligenceError } from '@athenaintel/sdk';

async function runAgentExample() {
  try {
    const client = new AthenaIntelligenceClient({
      apiKey: process.env.ATHENA_API_KEY,
      // Optional: override baseUrl for custom environments
      // baseUrl: 'https://your-custom-api.example.com',
    });

    // Multi-tool research request
    const request: AthenaIntelligence.GeneralAgentRequest = {
      config: {
        enabled_tools: ['search', 'browse'],
        system_prompt: 'You are a helpful research assistant. Use search and browse tools to find comprehensive information.',
        model: 'gpt-4-turbo-preview',
      },
      messages: [
        {
          content: 'Research the latest developments in AI and provide a detailed summary with sources.',
          role: 'user',
          type: 'user',
        },
      ],
    };

    console.log('Sending request to General Agent...');
    const response = await client.agents.general.invoke(request);
    
    console.log('Response received:');
    console.log(JSON.stringify(response, null, 2));
  } catch (error) {
    if (error instanceof AthenaIntelligenceError) {
      console.error(`Athena API error (${error.statusCode}): ${error.message}`);
    } else {
      console.error('Unexpected error:', error);
    }
  }
}

runAgentExample();
```