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

# Use Models Directly

> Access Athena's models directly with the TypeScript SDK

This example shows how to use Athena's language models directly when building with our TypeScript SDK. You can use the General Agent without tools to access models directly for simple text generation tasks.

Key features:

* Use any model available in your workspace
* Full TypeScript support with type safety
* Efficient async/await patterns
* Batch processing capabilities

### 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 Model Usage

Use the General Agent without tools to access models directly:

```typescript
const request: AthenaIntelligence.GeneralAgentRequest = {
  config: {
    model: 'gpt-4-turbo-preview',
  },
  messages: [
    {
      content: 'What is the capital of France?',
      role: 'user',
      type: 'user',
    },
  ],
};

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

### Available Models

Specify models explicitly in the config. Common models include:

```typescript
// Use Claude models
const claudeRequest: AthenaIntelligence.GeneralAgentRequest = {
  config: {
    model: 'claude-3-5-sonnet-20241022',
  },
  messages: [
    {
      content: 'Who are you and what can you help me with?',
      role: 'user',
      type: 'user',
    },
  ],
};

const claudeResponse = await client.agents.general.invoke(claudeRequest);

// Use GPT models
const gptRequest: AthenaIntelligence.GeneralAgentRequest = {
  config: {
    model: 'gpt-4-turbo-preview',
  },
  messages: [
    {
      content: 'Explain quantum computing in simple terms',
      role: 'user',
      type: 'user',
    },
  ],
};

const gptResponse = await client.agents.general.invoke(gptRequest);

// Use other models
const mistralRequest: AthenaIntelligence.GeneralAgentRequest = {
  config: {
    model: 'mistral-large-2407',
  },
  messages: [
    {
      content: 'Write a haiku about programming',
      role: 'user',
      type: 'user',
    },
  ],
};

const mistralResponse = await client.agents.general.invoke(mistralRequest);
```

### System Messages and Context

Use system messages to prime the model's behavior:

```typescript
const systemRequest: AthenaIntelligence.GeneralAgentRequest = {
  config: {
    model: 'gpt-4-turbo-preview',
  },
  messages: [
    {
      content: 'You are a helpful coding assistant specializing in TypeScript and Node.js.',
      role: 'system',
      type: 'system',
    },
    {
      content: 'How do I handle async errors in TypeScript?',
      role: 'user',
      type: 'user',
    },
  ],
};

const systemResponse = await client.agents.general.invoke(systemRequest);
console.log('System-primed response:', systemResponse);
```

### Batch Processing

Process multiple prompts efficiently using Promise.all:

```typescript
const prompts = [
  'Explain the theory of relativity',
  'What is machine learning?',
  'How does photosynthesis work?',
  'Describe the water cycle',
];

// Create requests for all prompts
const batchRequests = prompts.map(prompt => ({
  config: {
    model: 'gpt-4-turbo-preview',
  },
  messages: [
    {
      content: prompt,
      role: 'user',
      type: 'user',
    },
  ],
}));

// Process all requests in parallel
const batchPromises = batchRequests.map(request =>
  client.agents.general.invoke(request)
);

const batchResults = await Promise.all(batchPromises);

// Process results
batchResults.forEach((result, index) => {
  console.log(`Response ${index + 1} (${prompts[index]}):`);
  console.log(JSON.stringify(result, null, 2));
  console.log('-'.repeat(50));
});
```

### Error Handling

Always include proper error handling for production applications:

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

try {
  const response = await client.agents.general.invoke({
    config: {
      model: 'gpt-4-turbo-preview',
    },
    messages: [
      {
        content: 'Hello, world!',
        role: 'user',
        type: 'user',
      },
    ],
  });

  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 direct model usage:

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

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

    // Simple text generation request
    const request: AthenaIntelligence.GeneralAgentRequest = {
      config: {
        model: 'gpt-4-turbo-preview',
      },
      messages: [
        {
          content: 'You are a creative writing assistant.',
          role: 'system',
          type: 'system',
        },
        {
          content: 'Write a short story about a robot learning to paint',
          role: 'user',
          type: 'user',
        },
      ],
    };

    console.log('Sending request to model...');
    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);
    }
  }
}

runDirectModelExample();
```

> Access Athena's models directly with the TypeScript SDK