Agnes Free Text

Use this skill to call Sapiens AI's Agnes-2.0-Flash text model through the Agnes API.

Credential Rule

Read the API key from the environment. Do not hardcode keys in prompts, scripts, skill files, commits, or shell history.

Preferred variable:

export AGNES_API_KEY="..."

The helper also accepts AGNES_TOKEN as a fallback.

Quick Start

Run a normal chat completion:

python3 scripts/agnes_text.py chat \
  --prompt "用三句话解释 Agent 为什么需要工具调用"

Use a system prompt and save the raw response JSON:

python3 scripts/agnes_text.py chat \
  --system "You are a concise technical writer." \
  --prompt "Explain tool calling for a beginner." \
  --output-json ./outputs/agnes-free-text/response.json

Pass tool definitions from JSON:

python3 scripts/agnes_text.py chat \
  --prompt "Decide whether a weather tool is needed." \
  --tools-json ./tools.json \
  --tool-choice auto

Validate the request shape without calling the API:

python3 scripts/agnes_text.py chat \
  --prompt "Write a short product intro." \
  --max-tokens 300 \
  --dry-run

Workflow

1. Clarify whether the user wants a direct answer, JSON-like structured output, coding help, or streaming output.
2. Use scripts/agnes_text.py for repeatable calls. Prefer --dry-run first when parameters are complex.
3. Keep the model fixed to agnes-2.0-flash unless the API docs are updated.
4. For multi-turn context, pass repeated --message role:content values instead of flattening the conversation into one prompt.
5. For tool calling, pass --tools-json as either an inline JSON array or a path to a JSON file.

Notes

• Endpoint: POST https://apihub.agnes-ai.com/v1/chat/completions
• Model: agnes-2.0-flash
• Request shape is compatible with OpenAI Chat Completions.
• Supported features include system prompts, multi-turn messages, streaming, tool definitions, and tool choice.
• If the API returns an authorization error, check AGNES_API_KEY first.

Reference

Read references/api.md when you need endpoint details, response fields, tool-calling shape, or streaming examples.