ask-my-agent

Minimal, zero-dependency AI agent with tool calling support. Works with any OpenAI-compatible API.

Install

npm install ask-my-agent

Configure

npx ask-my-agent config

Prompts for:

• Base API — OpenAI-compatible endpoint (e.g., https://api.openai.com/v1)
• API Key — Your API key (can be empty)
• Model — Model name (e.g., gpt-4o)
• Native tool calling — Use API-native tools param (modern LLMs) or JSON-in-system-prompt mode (older models)

Config saved to ~/.askagentrc.

CLI usage

npx ask-my-agent config            # Configuration wizard
npx ask-my-agent agent "prompt"    # Run agent with all built-in tools

Library usage

const ama = require("ask-my-agent");

// Sync agent
let sum = {
  function: (a, b) => a + b,
  description: "Calculate A+B",
  inputs: [{ type: "int", description: "A" }, { type: "int", description: "B" }]
};

let result = ama.askSync("What is 2+2?", { sum }, (text) => {
  console.log("[iteration]", text);
});
console.log(result);

// Async agent
ama.ask("What is 2+2?", { sum }, (text) => {
  console.log("[iteration]", text);
}).then(console.log);

// Config queries
console.log(ama.getModel());
console.log(ama.isNativeToolCalling());

Built-in tools

Accessible via ama.tools:

| Tool | Description | |------|-------------| | webFetch | Fetch a URL's content | | javascript | Execute JS code (sandboxed via vm) | | read | Read a file (relative path only) | | bash | Execute bash commands | | grep | Search file contents by regex | | write | Write content to a file | | edit | Replace oldString with newString in a file |

All file tools reject absolute paths and detect path traversal.

How tool calling works

Native mode (nativeToolCalling: true): Uses the API's tools/tool_choice parameter. The model natively selects and calls tools.

JSON mode (nativeToolCalling: false): Tool definitions are embedded in the system prompt. The model responds with {"tool":"name","args":[...]} or {"response":"..."}, parsed each iteration. Works with older models that don't support native tool calling.

API

ama.askSync(prompt, tools, onIteration, debugTools?): string

Synchronous agent loop. Returns final answer.

• prompt — user message
• tools — object of tool definitions { name: { function, description, inputs } }
• onIteration(text) — called when the model outputs text alongside tool calls (intermediate thinking), NOT for the final answer
• debugTools — when true, prints [tool] name({"arg":"val"}) to stderr on each tool execution (default false)

ama.ask(prompt, tools, onIteration, debugTools?): Promise<string>

Async version of the agent loop. Same parameters as askSync.

ama.getModel(): string

Returns the model name from the active config.

ama.isNativeToolCalling(): boolean

Returns whether the active config uses native tool calling.

Tool definition format

{
  function: (arg1, arg2) => result,
  description: "What this tool does",
  inputs: [
    { type: "string", description: "First argument" },
    { type: "int", description: "Second argument" }
  ]
}

License

Unlicense — see LICENSE.

Changelog

0.0.5

• Fixed SSE parsing for providers with comment lines (e.g. : OPENROUTER PROCESSING)
• Agent now uses streaming API (stream: true) to prevent timeouts on thinking models

0.0.4

• Streaming API support — all requests use stream: true with SSE parsing
• Internal refactor: apiCallSync/apiCallAsync handle both SSE and JSON responses

0.0.3

• Safe .content access with || {} fallback for malformed API responses
• Proper API error surfacing when response contains error field
• debugTools shows tool args: [tool] name({...})

0.0.2

• Config file changed to ~/.askagentrc
• Built-in read/write/grep/edit tools reject absolute paths and detect traversal
• stripThink removes <think>...</think> from model output
• Tool execution errors return descriptive messages instead of crashing
• debugTools parameter controls stderr tool logging
• Stdin-piped curl (-d @-) eliminates E2BIG on large payloads
• Tool results truncated at 4000 chars
• CLI subcommands: config and agent

0.0.1

• Initial release with askSync, ask, getModel, isNativeToolCalling
• Dual tool calling: native (OpenAI tools param) and JSON-in-system-prompt mode
• 7 built-in tools: webFetch, javascript, read, bash, grep, write, edit
• Multi-config support via ~/.askagentrc