# Agent

> Give a goal in plain language; the agent searches, reads and answers with citations.

Source: http://localhost:3000/docs/endpoints/agent

## Agent: `POST /v1/agent/`

Give a goal; get a cited result plus the searches used to reach it. Cost: 4 credits.

```bash
curl -X POST https://api.hushsearch.io/v1/agent/ \
  -H "X-API-Key: hs_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "goal": "Compare the licenses of FastAPI and Django",
  "include_search": true
}'
```

The agent plans its own searches for the goal, reads the most useful pages and returns a cited answer.

## Parameters

| Field | Type | Default | Notes |
|---|---|---|---|
| `goal` | string | — | **Required.** 1–2,000 characters. |
| `max_results` | integer | — | Upper bound on sources read. |
| `include_search` | boolean | `false` | Also return the raw search hits the agent used. |

## Response

```json
{
  "goal": "Compare the licences of the top three open-source vector databases",
  "answer": "…",
  "sources": [{ "index": 1, "title": "…", "url": "https://…" }],
  "citation_count": 3,
  "search_results": null,
  "credits_used": 4,
  "credits_remaining": 496,
  "response_time_ms": 8900
}
```
