@spec create_agent(Keyword.t()) :: Luagents.Agent.t()

Create a new agent with custom configuration.

Options

• :name - Agent name (default: "Luagent")
• :llm - LLM instance (default: Anthropic Claude)
• :tools - Map of available tools (default: builtin tools)
• :max_iterations - Maximum reasoning iterations (default: 10)
• :memory - Initial memory state (default: empty)

Examples

# Basic agent
agent = Luagents.create_agent()

# Custom agent with Ollama
agent = Luagents.create_agent(
  name: "LocalAgent",
  llm: Luagents.create_llm(:ollama, model: "mistral"),
  max_iterations: 15
)

# Agent with custom tools
agent = Luagents.create_agent(tools: %{
  "custom" => Luagents.create_tool("custom", "Custom tool", [], fn _ -> "Custom tool" end)
})

@spec create_llm(Luagents.LLM.provider(), Keyword.t()) :: Luagents.LLM.t()

Create an LLM instance for use with agents.

Providers

• :anthropic - Claude models (requires ANTHROPIC_API_KEY)
• :ollama - Local Ollama models (requires Ollama server running)

Examples

# Anthropic Claude model
llm = Luagents.create_llm(:anthropic, model: "claude-3-haiku-20240307")

# Ollama with local model
llm = Luagents.create_llm(:ollama, model: "mistral")

# Custom Ollama host
llm = Luagents.create_llm(:ollama, model: "mistral", host: "http://192.168.1.100:11434")

@spec create_tool(
  String.t(),
  String.t(),
  [Luagents.Tool.parameter()],
  Luagents.Tool.func() | Luagents.Tool.api()
) :: Luagents.Tool.t()

Create a custom tool for use with agents.

Parameters

• name - Tool name (used in Lua code)
• description - Human-readable description
• parameters - List of parameter specifications
• function_or_api - Function that executes the tool or a module that implements the deflua API

Examples

# Simple tool with no parameters
greet_tool = Luagents.create_tool(
  "greet",
  "Say hello",
  [],
  fn _ -> "Hello, World!" end
)

# Tool with parameters
power_tool = Luagents.create_tool(
  "power",
  "Raise a number to a power",
  [
    %{name: "base", type: :number, description: "Base number", required: true},
    %{name: "exponent", type: :number, description: "Exponent", required: true}
  ],
  fn [base, exp] -> :math.pow(base, exp) end
)

# Tool with deflua macro API
defmodule WebSearch do
  use Lua.API

  deflua search(query) do
    # Implement search logic here
  end
end

tool = Luagents.create_tool(
  "search",
  "Search the web",
  [%{name: "query", type: :string, description: "Search query", required: true}],
  WebSearch
)

@spec get_agent_info(Luagents.Agent.t()) :: map()

Get agent configuration details.

Examples

agent = Luagents.create_agent(name: "TestBot", max_iterations: 5)
info = Luagents.get_agent_info(agent)
# => %{name: "TestBot", max_iterations: 5, tool_count: 4, memory_size: 0}

@spec get_agent_memory(Luagents.Agent.t()) :: [Luagents.Memory.message()]

Get the current memory state of an agent.

Returns the conversation history as a list of messages.

Examples

agent = Luagents.create_agent()
# ... run some tasks ...
messages = Luagents.get_agent_memory(agent)

@spec reset_agent_memory(Luagents.Agent.t()) :: Luagents.Agent.t()

Create an agent with cleared memory but same configuration.

Useful for starting fresh conversations with the same agent setup.

Examples

agent = Luagents.create_agent(name: "Bot")
# ... run some tasks ...
fresh_agent = Luagents.reset_agent_memory(agent)

@spec run(String.t(), Keyword.t()) :: {:ok, String.t()} | {:error, String.t()}

Run a task with the default agent configuration.

Uses Anthropic Claude by default with all built-in tools.

Options

• :tools - Map of tools to provide to the agent
• :llm - LLM instance to use (defaults to Ollama)
• :max_iterations - Maximum reasoning iterations (default: 10)
• :name - Agent name for identification

Examples

# Simple calculation
{:ok, answer} = Luagents.run("What is 10 + 20?")

# With custom tools
custom_tools = Map.merge(Luagents.builtin_tools(), %{
  "greet" => Luagents.create_tool("greet", "Say hello", [], fn _ -> {:ok, "Hello!"} end)
})
{:ok, response} = Luagents.run("Greet me", tools: custom_tools)

@spec run_with_agent(Luagents.Agent.t(), String.t()) ::
  {:ok, String.t()} | {:error, String.t()}

Run a task with a specific agent instance.

This allows you to reuse an agent across multiple tasks, maintaining any stateful configuration while getting fresh memory for each task.

Examples

agent = Luagents.create_agent(name: "MathBot")

{:ok, result1} = Luagents.run_with_agent(agent, "What is 5 + 3?")
{:ok, result2} = Luagents.run_with_agent(agent, "What is 10 * 4?")