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

ReAct (Reasoning + Acting) — start here

The standard choice. Alternates between thinking and acting:

import dspy

agent = dspy.ReAct(
    "question -> answer",
    tools=[search, calculate],
    max_iters=5,  # max steps before stopping
)

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

CodeAct — for code-heavy tasks

For tasks where writing and executing code is more natural:

agent = dspy.CodeAct(
    "question -> answer",
    tools=[search, calculate],
    max_iters=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 the full LangChain/LangGraph API reference, see docs/langchain-langgraph-reference.md.

Key patterns

• Start with ReAct — it's the most general-purpose action module
• Keep tools simple — each tool should do one thing well
• Set max_iters to prevent infinite loops (default is usually fine)
• Use descriptive docstrings — the AI uses them to decide when to call each tool
• Test without optimization first — action AI often works well zero-shot
• Add assertions for safety — use dspy.Assert to prevent dangerous tool calls

Additional resources

• For worked examples (calculator, search, APIs), see examples.md
• Need multiple agents working together (not just one)? Use /ai-coordinating-agents
• Next: /ai-improving-accuracy to measure and improve your AI