Ai Taking Actions

Build AI That Takes Actions

Guide the user through building AI that reasons and takes actions — calling APIs, using tools, and completing multi-step tasks. Uses DSPy's ReAct and CodeAct agent modules.

Step 1: Understand the use case

Ask the user: 1. What should the AI do? (answer questions, call APIs, perform calculations, search, etc.) 2. What tools does it need? (calculator, search, database, APIs, file system, etc.) 3. How many steps might it take? (simple tool call vs. multi-step reasoning)

Step 2: Define tools

Tools are Python functions with type hints and docstrings. DSPy uses these to tell the AI what's available:

def search(query: str) -> str:
    """Search the web for information."""
    # Your search implementation
    return "search results..."

def calculate(expression: str) -> float:
    """Evaluate a mathematical expression."""
    return dspy.PythonInterpreter({}).execute(expression)

def lookup_database(table: str, query: str) -> str:
    """Query the database for records matching the query."""
    # Your database logic
    return "query results..."

Tool requirements:

• Type hints on all parameters and return type
• Docstring explaining what the tool does
• Return a string (or something that converts to string)

Step 3: Build the AI

Choose your agent module

ReAct (Reasoning + Acting) — start here

The standard choice. Alternates between thinking and acting:

import dspy

lm = dspy.LM("openai/gpt-4o-mini")  # or "anthropic/claude-sonnet-4-5-20250929", etc.
dspy.configure(lm=lm)

agent = dspy.ReAct(
    "question -> answer",
    tools=[search, calculate],
    max_iters=8,  # default is 20; lower for simple tasks to save cost
)

result = agent(question="What is the population of France divided by 3?")
print(result.answer)

CodeAct — for code-heavy tasks

Writes and executes Python code. Only accepts pure functions as tools — no callable objects or undeclared dependencies:

agent = dspy.CodeAct(
    "question -> answer",
    tools=[calculate],  # pure functions only
    max_iters=5,  # default is 5
)

result = agent(question="Calculate the compound interest on $1000 at 5% for 10 years")
print(result.answer)

Custom AI with state

class ResearchBot(dspy.Module):
    def __init__(self):
        self.agent = dspy.ReAct(
            "question, context -> answer",
            tools=[search, lookup_database],
            max_iters=8,
        )

    def forward(self, question):
        # Add initial context or pre-processing
        context = "Use search for general questions, database for specific records."
        return self.agent(question=question, context=context)

Step 4: Test the quality

def action_metric(example, prediction, trace=None):
    # Check if the final answer is correct
    return prediction.answer.strip().lower() == example.answer.strip().lower()

# For open-ended tasks, use an AI judge
class JudgeResult(dspy.Signature):
    """Judge if the AI's answer correctly addresses the question."""
    question: str = dspy.InputField()
    expected: str = dspy.InputField()
    actual: str = dspy.InputField()
    is_correct: bool = dspy.OutputField()

def judge_metric(example, prediction, trace=None):
    judge = dspy.Predict(JudgeResult)
    result = judge(
        question=example.question,
        expected=example.answer,
        actual=prediction.answer,
    )
    return result.is_correct

Step 5: Improve accuracy

# Optimize the AI's reasoning prompts
optimizer = dspy.BootstrapFewShot(metric=action_metric, max_bootstrapped_demos=4)
optimized = optimizer.compile(agent, trainset=trainset)

For action-taking AI, MIPROv2 often works better since it can optimize the reasoning instructions:

optimizer = dspy.MIPROv2(metric=action_metric, auto="medium")
optimized = optimizer.compile(agent, trainset=trainset)

Using LangChain tools

LangChain has 100+ pre-built tools (search engines, Wikipedia, SQL databases, web scrapers, etc.). Convert any of them to DSPy tools with one line:

import dspy
from langchain_community.tools import DuckDuckGoSearchRun, WikipediaQueryRun
from langchain_community.utilities import WikipediaAPIWrapper

# Convert LangChain tools to DSPy tools
search = dspy.Tool.from_langchain(DuckDuckGoSearchRun())
wikipedia = dspy.Tool.from_langchain(WikipediaQueryRun(api_wrapper=WikipediaAPIWrapper()))

# Use in any DSPy agent
agent = dspy.ReAct(
    "question -> answer",
    tools=[search, wikipedia],
    max_iters=5,
)

When to use LangChain tools vs writing your own:

Install the tools you need:

pip install langchain-community  # DuckDuckGo, Wikipedia, requests, etc.

For more LangChain tools, see the LangChain community tools docs.

When NOT to use agents

• Single-step tasks — if the AI just needs to answer a question or classify text, use dspy.Predict or dspy.ChainOfThought instead. Agents add overhead (multiple LM calls per request).
• Deterministic workflows — if the steps are always the same, write the code yourself and use DSPy modules for the LM-powered steps only. Agents shine when the path depends on intermediate results.
• Cost-sensitive applications — each ReAct iteration is a separate LM call. A 5-step agent costs roughly 5x a single Predict call. Consider whether the task justifies this.

Gotchas

• Claude sets `max_iters=5` for ReAct but the default is 20. The API default of 20 is generous — for most tasks, 5-10 iterations suffice. Set it explicitly to control cost, but do not assume 5 is the framework default.
• CodeAct only accepts pure functions as tools. Passing callable objects, class instances, or functions with undeclared dependencies will fail silently or error. If your tool has external deps, use ReAct instead.
• Claude forgets to call `dspy.configure(lm=lm)` before creating agents. The agent will fail at runtime with confusing errors if no LM is configured. Always configure the LM before instantiating any module.
• Tool docstrings are the AI's only guidance on when to call each tool. Vague docstrings like "do stuff" cause the agent to misroute. Write docstrings that describe what the tool does and when to use it, as if explaining to a colleague.
• Claude wraps tool return values in complex objects instead of strings. DSPy agents expect tools to return strings (or values that convert cleanly to strings). Returning dicts, lists, or custom objects can cause the agent to misinterpret results.

Cross-references

Install any skill: npx skills add lebsral/DSPy-Programming-not-prompting-LMs-skills --skill <name>

• Multiple agents working together — see /ai-coordinating-agents
• Measure and improve accuracy — see /ai-improving-accuracy
• ReAct and CodeAct module details — see /dspy-react or /dspy-code-act (if available)
• Signatures for defining agent I/O — see /dspy-signatures
• Install `/ai-do` if you do not have it — it routes any AI problem to the right skill and is the fastest way to work: npx skills add lebsral/DSPy-Programming-not-prompting-LMs-skills --skill ai-do

Additional resources

• For worked examples (calculator, search, APIs), see examples.md

Action-Taking AI Examples

Calculator

import dspy

lm = dspy.LM("openai/gpt-4o-mini")  # or "anthropic/claude-sonnet-4-5-20250929", etc.
dspy.configure(lm=lm)

def evaluate_math(expression: str) -> float:
    """Evaluate a mathematical expression and return the result."""
    return dspy.PythonInterpreter({}).execute(expression)

agent = dspy.ReAct("question -> answer: float", tools=[evaluate_math])

result = agent(question="What is (15 * 7 + 23) / 4?")
print(f"Answer: {result.answer}")  # 32.0

# Multi-step math
result = agent(question="If I have 3 boxes with 12 items each, and I remove 7 items total, how many are left?")
print(f"Answer: {result.answer}")  # 29.0

Search + Calculator

def search_wikipedia(query: str) -> str:
    """Search Wikipedia for factual information."""
    results = dspy.ColBERTv2(url="http://20.102.90.50:2017/wiki17_abstracts")(query, k=3)
    return "\n".join([x["text"] for x in results])

def evaluate_math(expression: str) -> float:
    """Evaluate a mathematical expression."""
    return dspy.PythonInterpreter({}).execute(expression)

agent = dspy.ReAct(
    "question -> answer",
    tools=[search_wikipedia, evaluate_math],
    max_iters=5,
)

# Requires both search and calculation
result = agent(
    question="What is the population of Tokyo divided by the population of Paris?"
)
print(result.answer)

API-Calling AI

import requests

def get_weather(city: str) -> str:
    """Get current weather for a city."""
    # Replace with your actual weather API
    resp = requests.get(f"https://wttr.in/{city}?format=3")
    return resp.text

def get_stock_price(symbol: str) -> str:
    """Get the current stock price for a ticker symbol."""
    # Replace with your actual stock API
    return f"{symbol}: $150.00"  # placeholder

agent = dspy.ReAct(
    "question -> answer",
    tools=[get_weather, get_stock_price],
    max_iters=3,
)

result = agent(question="What's the weather in San Francisco?")
print(result.answer)

Research Bot with Custom Module

def search(query: str) -> str:
    """Search for information on the web."""
    results = dspy.ColBERTv2(url="http://20.102.90.50:2017/wiki17_abstracts")(query, k=3)
    return "\n".join([x["text"] for x in results])

class ResearchBot(dspy.Module):
    """AI that researches a topic and provides a structured summary."""
    def __init__(self):
        self.researcher = dspy.ReAct(
            "topic -> findings",
            tools=[search],
            max_iters=5,
        )
        self.summarize = dspy.ChainOfThought(
            "topic, findings -> summary, key_facts: list[str]"
        )

    def forward(self, topic):
        research = self.researcher(topic=topic)
        return self.summarize(topic=topic, findings=research.findings)

bot = ResearchBot()
result = bot(topic="The history of the Python programming language")
print(f"Summary: {result.summary}")
print(f"Key facts: {result.key_facts}")

Safety with Refine

def safe_search(query: str) -> str:
    """Search for information from trusted sources."""
    results = dspy.ColBERTv2(url="http://20.102.90.50:2017/wiki17_abstracts")(query, k=3)
    return "\n".join([x["text"] for x in results])

class SafeBot(dspy.Module):
    def __init__(self):
        self.agent = dspy.ReAct("question -> answer", tools=[safe_search], max_iters=3)

    def forward(self, question):
        return self.agent(question=question)


def safe_bot_reward(args, pred):
    """Reward function: hard require a non-empty answer, soft encourage confidence."""
    if not pred.answer or len(pred.answer.strip()) == 0:
        return 0.0  # hard: must produce an answer
    score = 1.0
    if "i don't know" in pred.answer.lower():
        score -= 0.2  # soft: encourage using the search tool more effectively
    return score

safe_bot = dspy.Refine(module=SafeBot(), N=3, reward_fn=safe_bot_reward, threshold=0.8)

Optimizing Action-Taking AI

# Training data
trainset = [
    dspy.Example(
        question="What is 9362158 divided by the year of birth of David Gregory?",
        answer="6780"
    ).with_inputs("question"),
    # ... more examples
]

# Optimize with MIPROv2 (good for reasoning instruction tuning)
optimizer = dspy.MIPROv2(metric=action_metric, auto="light")
optimized = optimizer.compile(agent, trainset=trainset)

# Save optimized version
optimized.save("optimized_agent.json")