Prompt engineering
Write prompts for /agent/ask that set the output shape, constraints, context, and mode.
This page covers prompt craft: wording, structure, and constraints. For protocol patterns (streaming, retries, multi-turn), see Examples.
Be specific about output shape
To improve an answer, tell the agent what "good" looks like: specify length, format, and tone up front.
Bad: "Tell me about TSMC."
Good: "Give me a 3-bullet brief on TSMC's competitive moat - one
sentence each, written for a public-equities analyst."Length, format, and audience are independent, so set each one when it matters.
Prefer constraints over hopes
For machine-readable output, pass output_schema
(recipe 7):
NeuroAPI validates the result against your schema. For prose, set the
constraints in the prompt. "Reply as JSON" is a hope. "Reply with a JSON object with keys
title (string), summary (string ≤ 200 chars), tags (array of
≤ 5 strings)" is a constraint.
curl -s https://api.neurobro.ai/api/v1/agent/ask \
-H "Content-Type: application/json" \
-H "X-API-Key: $NEUROAPI_KEY" \
-d '{
"prompt": "Read the earnings transcript excerpt below and respond with a JSON object with keys: ticker (string), sentiment (one of \"bullish\" | \"neutral\" | \"bearish\"), drivers (array of <=5 short strings). Output the JSON and nothing else.\n\nTRANSCRIPT:\n<paste here>"
}'Always validate the parsed result on your side. A field-level
constraint in a prompt is a strong suggestion, not a guarantee, so
enforce invariants in your code. To get an object back in a shape you
define, pass output_schema as shown in
recipe 7 in Examples.
Use message_history for context, not the prompt
When you need the model to remember earlier turns, send them in
message_history, not concatenated into prompt. Two reasons:
- It scans cleanly. The role boundaries are explicit; the model can tell what is the new question versus prior context.
- It composes. Your code can trim the oldest turns when the
transcript grows; rewriting a long blob
promptis harder.
The API is stateless, so on every call you re-send the entire history you want considered. See recipe 2 in Examples.
Pick a mode deliberately
| Mode | What it's for |
|---|---|
fast | Quick answers with core market knowledge. Good for asset checks, market sentiment, and high-volume financial Q&A. |
smart (default) | Deeper reasoning and more market context for complex questions. Good for technical analysis, trade setups, and fundamental stock research. |
max | The deepest research: multi-asset investigations and fundamental analysis with broad market coverage. |
When in doubt, leave it at smart (the server default) and instrument
usage.cost_units per call so you can see what you're spending.
Plan prices and quotas are in Pricing.
Streaming changes how you prompt
When stream: true, the user sees the prefix first. Optimize for
top-down readability:
- Don't ask for "a summary at the end" - the user reads the beginning before the end exists.
- Do ask for the conclusion up front, details after. "Start with the answer in one sentence, then expand."
- Do structure long answers as numbered sections so the user can parse them as they arrive.
Common pitfalls
What not to put in prompts
- API keys or any secret you wouldn't paste in a third-party form.
- Customer PII you don't have a basis to share with model providers.
- Long blobs of unstructured input you haven't validated for size - set a budget on your side and truncate before sending.
Security & data covers what NeuroAPI stores
and what it doesn't. If you have a compliance constraint that needs a
specific data boundary, contact [email protected].