# POST /agent-chat

**Resource:** [Evie (In-App Agent)](./evie.md)  
**Scopes:** _none_  
**Write operation:** yes

Run a single Evie conversation turn and stream the result via Server-Sent Events (SSE). The caller supplies a tp_oauth_* token (from /evie-grant) as the Bearer credential. Evie uses the token scopes to determine which CRM tools she can call, dispatches tool calls in-process (no HTTP round-trip per tool), and streams text + tool-call events back in real time. The thread is created automatically on the first message; supply thread_id on subsequent messages to continue a conversation. Model: TrustPager AI Standard (fast) by default; prefix your message with /think for TrustPager AI Advanced.

## Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `message` | body | string | yes | User message text. Prefix with /think to use the advanced reasoning model. |
| `thread_id` | body | uuid | no | Existing thread ID for multi-turn conversations. Omit to start a new thread. |
| `context` | body | object | no | Portal context for grounding Evie in the user current location. Include current_route (e.g. /crm/opportunities/123), entity_type (opportunity\|contact\|company), and entity_id when on a detail page. |
| `attachments` | body | array | no | Image attachments (jpeg, png, gif, webp). Each item: { media_type, data (base64 without data: prefix), secure_file_id? }. Max 5MB per image. |

## Request example

```bash
POST /functions/v1/agent-chat
Authorization: Bearer tp_oauth_a1b2c3d4e5f6...
Content-Type: application/json

{
  "message": "How many open opportunities do we have in the Sales pipeline?",
  "thread_id": "a1b2c3d4-...",
  "context": {
    "current_route": "/crm/pipelines",
    "entity_type": null,
    "entity_id": null
  }
}
```

## Response example

```json
-- SSE stream events --

event: thread
data: {"thread_id":"a1b2c3d4-..."}

event: tool_use
data: {"id":"tu_abc","name":"list_pipelines","input":{},"status":"running","api_path":"GET /pipelines","portal_path":"/crm/pipelines"}

event: tool_result
data: {"id":"tu_abc","status":"ok","http_status":200,"body":{...},"credits_charged":0,"portal_path":"/crm/pipelines"}

event: tool_use
data: {"id":"tu_def","name":"list_opportunities","input":{"pipeline_id":"...","status":"open"},"status":"running","api_path":"GET /opportunities"}

event: tool_result
data: {"id":"tu_def","status":"ok","http_status":200,"body":{"data":[...],"pagination":{...}},"credits_charged":0}

event: text
data: {"text":"You have 12 open opportunities in the Sales pipeline, worth a combined $240,000."}

event: usage
data: {"model":"TrustPager AI Standard","input_tokens":2150,"output_tokens":48,"llm_credits_charged":3,"tool_credits_charged":0,"total_credits_charged":3,"routing_reason":"default"}

event: done
data: {"thread_id":"a1b2c3d4-..."}
```

## Notes

- This endpoint streams Server-Sent Events (SSE). Use EventSource or fetch with stream reading on the client.
- Thread ownership is enforced server-side: you can only continue threads created by your (user, company) pair.
- Tool calls that return HTTP 202 with an approval_id are queued for human review at /settings/api?tab=approvals. Evie surfaces these as "Pending approval" cards in the UI.
- Per-turn credits charged are reported in the usage event. LLM credits are debited post-turn; tool credits vary by tool.
- The /think prefix upgrades the model for that turn. This uses more credits.
- Max tool-call iterations per turn: 12. If the conversation requires more than 12 sequential tool calls, use /agent-chat-compact to summarise and continue.

---
Base URL: `https://api.trustpager.com/functions/v1/api/v1` — Auth: `Authorization: Bearer YOUR_API_KEY`