Build an agent
FairCrawl’s /agent endpoint is the fastest path when the user intent is natural language and the route selection should happen inside the platform instead of in your app.
What the agent can do
The live loop can call these tools internally:
scrapemapinteractresearchfinalize
Start with a small budget
Budgeted agent call
```bash
curl https://api.faircompany.ai/v1/crawl/agent \
-X POST \
-H "Authorization: Bearer fc_live_xxx" \
-H "Content-Type: application/json" \
-d '{
"instruction": "Find Stripe's current standard card pricing and return the answer with sources.",
"max_steps": 6,
"budget_usd": 0.05
}'
```
```ts
const answer = await fc.agent({
instruction: "Find Stripe's current standard card pricing and return the answer with sources.",
max_steps: 6,
budget_usd: 0.05,
});
console.log(answer.answer);
console.log(answer.sources);
```
```python
answer = fc.agent(
"Find Stripe's current standard card pricing and return the answer with sources.",
max_steps=6,
budget_usd=0.05,
)
print(answer.answer)
print(answer.sources)
```
```json
{
"tool": "faircrawl_agent",
"arguments": {
"instruction": "Find Stripe's current standard card pricing and return the answer with sources.",
"max_steps": 6,
"budget_usd": 0.05
}
}
```
Prefer structured final answers
When you know the output shape, ask for JSON and provide json_schema.
Structured JSON output
```bash
curl https://api.faircompany.ai/v1/crawl/agent \
-X POST \
-H "Authorization: Bearer fc_live_xxx" \
-H "Content-Type: application/json" \
-d '{
"instruction": "Compare Notion and Confluence pricing for teams under 50 seats.",
"response_format": "json",
"json_schema": {
"type": "object",
"properties": {
"winner": { "type": "string" },
"notes": { "type": "array", "items": { "type": "string" } }
},
"required": ["winner", "notes"]
}
}'
```
```ts
const result = await fc.agent({
instruction: "Compare Notion and Confluence pricing for teams under 50 seats.",
response_format: "json",
json_schema: {
type: "object",
properties: {
winner: { type: "string" },
notes: { type: "array", items: { type: "string" } },
},
required: ["winner", "notes"],
},
});
console.log(result.answer);
```
```python
result = fc.agent(
"Compare Notion and Confluence pricing for teams under 50 seats.",
response_format="json",
json_schema={
"type": "object",
"properties": {
"winner": {"type": "string"},
"notes": {"type": "array", "items": {"type": "string"}},
},
"required": ["winner", "notes"],
},
)
print(result.answer)
```
```json
{
"tool": "faircrawl_agent",
"arguments": {
"instruction": "Compare Notion and Confluence pricing for teams under 50 seats.",
"response_format": "json",
"json_schema": {
"type": "object",
"properties": {
"winner": { "type": "string" },
"notes": { "type": "array", "items": { "type": "string" } }
},
"required": ["winner", "notes"]
}
}
}
```
Production pattern
- Use a narrow instruction instead of a broad product brief.
- Set
max_stepslow first, then raise it only if you can prove you need more search breadth. - Keep
budget_usdexplicit so downstream latency and cost are predictable. - Use
response_format: "json"whenever your app needs a stable parser boundary.