Add LLM tools and agents to README, refine agent descriptions across …

…docs and code.

README.md

@@ -96,6 +96,35 @@ Grep or fuzz search [files](https://microsoft.github.io/genaiscript/reference/sc
 const { files } = await workspace.grep(/[a-z][a-z0-9]+/, "**/*.md")
 ```
 
+### LLM Tools
+
+Register JavaScript functions as **tools**.
+
+```js
+defTool(
+    "weahter",
+    "query a weather web api",
+    { location: "string" },
+    async (args) =>
+        await fetch(`https://weather.api.api/?location=${args.location}`)
+)
+```
+
+### LLM Agents
+
+Register JavaScript functions as **tools** and combine tools + prompt into agents.
+
+```js
+defAgent(
+    "git",
+    "Query a repository using Git to accomplish tasks.",
+    `Your are a helpfull LLM agent that can use the git tools to query the current repository.
+    Answer the question in QUERY.
+    - The current repository is the same as github repository.`,
+    { model, system: ["system.github_info"], tools: ["git"] }
+)
+```
+
 ### 🔍 RAG Built-in
 
 [Vector search](https://microsoft.github.io/genaiscript/reference/scripts/vector-search/).

docs/src/components/BuiltinAgents.mdx

@@ -6,8 +6,8 @@ import { LinkCard } from '@astrojs/starlight/components';
 
 ### Builtin Agents
 
-<LinkCard title="agent fs" description="Queries files to accomplish tasks" href="/genaiscript/reference/scripts/system#systemagent_fs" />
-<LinkCard title="agent git" description="Agent that can query a repository using Git to accomplish tasks. Provide all the context information available to execute git queries." href="/genaiscript/reference/scripts/system#systemagent_git" />
-<LinkCard title="agent github" description="Agent that can query GitHub  to accomplish tasks" href="/genaiscript/reference/scripts/system#systemagent_github" />
-<LinkCard title="agent interpreter" description="Run code interpreters for Python, Math. Use this agent to ground computation questions." href="/genaiscript/reference/scripts/system#systemagent_interpreter" />
-<LinkCard title="agent user_input" description="Ask user for input to confirm, select or answer the question in the query. The message should be very clear and provide all the context." href="/genaiscript/reference/scripts/system#systemagent_user_input" />
+<LinkCard title="agent fs" description="query files to accomplish tasks" href="/genaiscript/reference/scripts/system#systemagent_fs" />
+<LinkCard title="agent git" description="query a repository using Git to accomplish tasks. Provide all the context information available to execute git queries." href="/genaiscript/reference/scripts/system#systemagent_git" />
+<LinkCard title="agent github" description="query GitHub to accomplish tasks" href="/genaiscript/reference/scripts/system#systemagent_github" />
+<LinkCard title="agent interpreter" description="run code interpreters for Python, Math. Use this agent to ground computation questions." href="/genaiscript/reference/scripts/system#systemagent_interpreter" />
+<LinkCard title="agent user_input" description="ask user for input to confirm, select or answer the question in the query. The message should be very clear and provide all the context." href="/genaiscript/reference/scripts/system#systemagent_user_input" />

docs/src/content/docs/reference/scripts/agents.mdx

@@ -11,6 +11,11 @@ GenAIScript defines an **agent** as a [tool](/genaiscript/reference/scripts/tool
 runs an [inline prompt](/genaiscript/reference/scripts/inline-prompts) to accomplish a task. The agent's LLM is typically augmented with
 additional tools.
 
+## Agent orchestration
+
+**GenAIScript does _not_ implement any agentic workflow or decision.**
+It relies entirely on [tools](/genaiscript/reference/scripts/tools) support built into the LLMs.
+
 ```mermaid
 flowchart TD
     query["query"] -->  |"why did the build fail?"| LLM
@@ -32,11 +37,6 @@ flowchart TD
     LLM --> |"the change at line 50 is wrong"| response["response"]
 ```
 
-## Agent orchestration
-
-**GenAIScript does _not_ implement any agentic workflow or decision.**
-It relies entirely on [tools](/genaiscript/reference/scripts/tools) support built into the LLMs.
-
 ## defAgent
 
 The `defAgent` function is used to define an agent that can be called by the LLM. It takes a JSON schema to define the input and expects a string output. The LLM autonomously decides to call this agent.

docs/src/content/docs/reference/scripts/system.mdx

@@ -113,7 +113,7 @@ const model = env.vars.agentFsModel
 
 defAgent(
     "fs",
-    "Queries files to accomplish tasks",
+    "query files to accomplish tasks",
     `Your are a helpfull LLM agent that can query the file system.
     Answer the question in QUERY.`,
     {
@@ -148,7 +148,7 @@ const model = env.vars.agentGitModel
 
 defAgent(
     "git",
-    "Agent that can query a repository using Git to accomplish tasks. Provide all the context information available to execute git queries.",
+    "query a repository using Git to accomplish tasks. Provide all the context information available to execute git queries.",
     `Your are a helpfull LLM agent that can use the git tools to query the current repository.
     Answer the question in QUERY.
     - The current repository is the same as github repository.`,
@@ -175,7 +175,7 @@ const model = env.vars.agentGithubModel
 
 defAgent(
     "github",
-    "Agent that can query GitHub  to accomplish tasks",
+    "query GitHub to accomplish tasks",
     `Your are a helpfull LLM agent that can query GitHub to accomplish tasks. Answer the question in QUERY.
     Prefer diffing job logs rather downloading entire logs which can be very large.`,
     {
@@ -211,7 +211,7 @@ system({
 const model = env.vars.agentInterpreterModel
 defAgent(
     "interpreter",
-    "Run code interpreters for Python, Math. Use this agent to ground computation questions.",
+    "run code interpreters for Python, Math. Use this agent to ground computation questions.",
     `You are an agent that can run code interpreters for Python, Math. Answer the question in QUERY.
     - Prefer math_eval for math expressions as it is much more efficient.
     - To use file data in python, prefer copying data files using python_code_interpreter_copy_files rather than inline data in code.
@@ -247,7 +247,7 @@ system({
 const model = env.vars.agentInterpreterModel
 defAgent(
     "user_input",
-    "Ask user for input to confirm, select or answer the question in the query. The message should be very clear and provide all the context.",
+    "ask user for input to confirm, select or answer the question in the query. The message should be very clear and provide all the context.",
     `Your task is to ask the question in QUERY to the user using the tools.
     - Use the best tool to interact with the user. 
     - do NOT try to interpret the meaning of the question, let the user answer.

packages/core/src/genaisrc/system.agent_fs.genai.mjs

@@ -6,7 +6,7 @@ const model = env.vars.agentFsModel
 
 defAgent(
     "fs",
-    "Queries files to accomplish tasks",
+    "query files to accomplish tasks",
     `Your are a helpfull LLM agent that can query the file system.
     Answer the question in QUERY.`,
     {

packages/core/src/genaisrc/system.agent_git.genai.mjs

@@ -6,7 +6,7 @@ const model = env.vars.agentGitModel
 
 defAgent(
     "git",
-    "Agent that can query a repository using Git to accomplish tasks. Provide all the context information available to execute git queries.",
+    "query a repository using Git to accomplish tasks. Provide all the context information available to execute git queries.",
     `Your are a helpfull LLM agent that can use the git tools to query the current repository.
     Answer the question in QUERY.
     - The current repository is the same as github repository.`,

packages/core/src/genaisrc/system.agent_github.genai.mjs

@@ -6,7 +6,7 @@ const model = env.vars.agentGithubModel
 
 defAgent(
     "github",
-    "Agent that can query GitHub  to accomplish tasks",
+    "query GitHub to accomplish tasks",
     `Your are a helpfull LLM agent that can query GitHub to accomplish tasks. Answer the question in QUERY.
     Prefer diffing job logs rather downloading entire logs which can be very large.`,
     {

packages/core/src/genaisrc/system.agent_interpreter.genai.mjs

@@ -5,7 +5,7 @@ system({
 const model = env.vars.agentInterpreterModel
 defAgent(
     "interpreter",
-    "Run code interpreters for Python, Math. Use this agent to ground computation questions.",
+    "run code interpreters for Python, Math. Use this agent to ground computation questions.",
     `You are an agent that can run code interpreters for Python, Math. Answer the question in QUERY.
     - Prefer math_eval for math expressions as it is much more efficient.
     - To use file data in python, prefer copying data files using python_code_interpreter_copy_files rather than inline data in code.

packages/core/src/genaisrc/system.agent_user_input.genai.mjs

@@ -5,7 +5,7 @@ system({
 const model = env.vars.agentInterpreterModel
 defAgent(
     "user_input",
-    "Ask user for input to confirm, select or answer the question in the query. The message should be very clear and provide all the context.",
+    "ask user for input to confirm, select or answer the question in the query. The message should be very clear and provide all the context.",
     `Your task is to ask the question in QUERY to the user using the tools.
     - Use the best tool to interact with the user. 
     - do NOT try to interpret the meaning of the question, let the user answer.

packages/core/src/runpromptcontext.ts

@@ -307,7 +307,7 @@ export function createChatGenerationContext(
             agentSystem,
             arrayify(tools)
         )
-        const agentDescription = dedent`Agent uses LLM to ${description}. available tools: 
+        const agentDescription = dedent`Agent that uses an LLM to ${description}.\nAvailable tools: 
         ${agentTools.map((t) => `- ${t.description}`).join("\n")}` // DO NOT LEAK TOOL ID HERE
 
         defTool(