> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vultlocal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Environment variables and configuration for Agent-TS

# Agent-TS Configuration

Agent-TS is configured through environment variables. Copy `.env.example` to `.env` and configure the required values.

## Environment Variables

### Required Variables

| Variable                | Description                       | Example             |
| ----------------------- | --------------------------------- | ------------------- |
| `OPENAI_API_KEY`        | OpenAI API key for GPT and Vision | `sk-...`            |
| `GATEWAY_API_KEY`       | OLIVE Gateway API key             | `olive_live_xxx...` |
| `WHATSAPP_VERIFY_TOKEN` | Webhook verification token        | `your-verify-token` |

### Optional Variables

| Variable              | Description           | Default               |
| --------------------- | --------------------- | --------------------- |
| `PORT`                | Server port           | `8000`                |
| `OPENAI_MODEL`        | OpenAI model to use   | `gpt-4o-mini`         |
| `OPENAI_ASSISTANT_ID` | Existing assistant ID | Auto-created          |
| `GATEWAY_URL`         | Gateway URL           | `http://gateway:8080` |
| `LOG_LEVEL`           | Logging level         | `info`                |

### AWS S3 Configuration

Required for KYC document storage:

| Variable                | Description            | Example               |
| ----------------------- | ---------------------- | --------------------- |
| `AWS_ACCESS_KEY_ID`     | AWS access key         | `AKIA...`             |
| `AWS_SECRET_ACCESS_KEY` | AWS secret key         | `...`                 |
| `AWS_S3_BUCKET_NAME`    | S3 bucket for KYC docs | `olive-kyc-documents` |
| `AWS_REGION`            | AWS region             | `us-east-1`           |

## Example Configuration

```env theme={null}
# Server
PORT=8000
LOG_LEVEL=info

# OpenAI
OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxxx
OPENAI_MODEL=gpt-4o-mini
# Leave empty to auto-create, or set existing ID
OPENAI_ASSISTANT_ID=

# OLIVE Gateway
GATEWAY_URL=http://gateway:8080
GATEWAY_API_KEY=olive_live_xxxxxxxxxxxxxxxx

# WhatsApp
WHATSAPP_VERIFY_TOKEN=your-secure-verify-token

# AWS S3 (for KYC documents)
AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
AWS_S3_BUCKET_NAME=olive-kyc-documents
AWS_REGION=us-east-1
```

## Configuration by Environment

<Tabs>
  <Tab title="Development">
    ```env theme={null}
    PORT=8000
    LOG_LEVEL=debug
    GATEWAY_URL=http://localhost:8080
    ```
  </Tab>

  <Tab title="Production">
    ```env theme={null}
    PORT=8000
    LOG_LEVEL=info
    GATEWAY_URL=https://demo.api.vultlocal.com
    ```
  </Tab>

  <Tab title="Docker">
    ```env theme={null}
    PORT=8000
    LOG_LEVEL=info
    GATEWAY_URL=http://gateway:8080
    ```
  </Tab>
</Tabs>

## OpenAI Configuration

### Model Selection

The agent supports various OpenAI models:

| Model         | Use Case                | Cost   |
| ------------- | ----------------------- | ------ |
| `gpt-4o-mini` | Default, fast responses | Low    |
| `gpt-4o`      | Complex reasoning       | Medium |
| `gpt-4-turbo` | High accuracy           | High   |

### Assistant Management

On first run, the agent creates an OpenAI Assistant with the configured tools. The assistant ID is logged and can be set in `OPENAI_ASSISTANT_ID` for subsequent runs to reuse the same assistant.

```bash theme={null}
# First run - creates new assistant
npm run dev
# Logs: Created assistant: asst_xxxxxxxxxxxxx

# Subsequent runs - set the ID to reuse
OPENAI_ASSISTANT_ID=asst_xxxxxxxxxxxxx npm run dev
```

## S3 Bucket Configuration

### Bucket Policy

The S3 bucket should be private with appropriate IAM permissions:

```json theme={null}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:GetObject",
        "s3:DeleteObject"
      ],
      "Resource": "arn:aws:s3:::olive-kyc-documents/*"
    }
  ]
}
```

### CORS Configuration

For pre-signed URL access:

```json theme={null}
[
  {
    "AllowedHeaders": ["*"],
    "AllowedMethods": ["GET", "PUT"],
    "AllowedOrigins": ["https://admin.olive.example.com"],
    "ExposeHeaders": [],
    "MaxAgeSeconds": 3000
  }
]
```

## Rate Limiting

Default rate limits (configurable in `rate-limiter.ts`):

| Limit                           | Value |
| ------------------------------- | ----- |
| Requests per minute (per phone) | 30    |
| Concurrent conversations        | 100   |
| Image uploads per hour          | 10    |

## Troubleshooting

### Common Issues

<AccordionGroup>
  <Accordion title="OpenAI API errors">
    * Verify `OPENAI_API_KEY` is valid
    * Check API quota and billing
    * Ensure network access to OpenAI endpoints
  </Accordion>

  <Accordion title="Gateway connection failures">
    * Verify `GATEWAY_URL` is reachable
    * Check `GATEWAY_API_KEY` is valid
    * Ensure gateway service is running
  </Accordion>

  <Accordion title="S3 upload failures">
    * Verify AWS credentials are correct
    * Check bucket exists and is accessible
    * Ensure IAM permissions are configured
  </Accordion>

  <Accordion title="WhatsApp webhook not verified">
    * Ensure `WHATSAPP_VERIFY_TOKEN` matches Meta configuration
    * Check endpoint is publicly accessible (HTTPS)
    * Verify URL in Meta Developer Console
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Tools Reference" icon="wrench" href="/agent-ts/tools">
    Available tool definitions
  </Card>

  <Card title="Webhooks" icon="webhook" href="/agent-ts/webhooks">
    WhatsApp integration setup
  </Card>
</CardGroup>