NeuroAPI
Best practicesPrompt engineering

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:

  1. It scans cleanly. The role boundaries are explicit; the model can tell what is the new question versus prior context.
  2. It composes. Your code can trim the oldest turns when the transcript grows; rewriting a long blob prompt is 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

ModeWhat it's for
fastQuick 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.
maxThe 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].

What's next

On this page