#add task

[jcmarchi]

Guide to Understanding, Building, and Optimizing API-Calling Agents

New Post has been published on https://thedigitalinsider.com/guide-to-understanding-building-and-optimizing-api-calling-agents/

Guide to Understanding, Building, and Optimizing API-Calling Agents

The role of Artificial Intelligence in technology companies is rapidly evolving;  AI use cases have evolved from passive information processing to proactive agents capable of executing tasks. According to a March 2025 survey on global AI adoption conducted by Georgian and NewtonX, 91% of technical executives in growth stage and enterprise companies are reportedly using or planning to use agentic AI.

API-calling agents are a primary example of this shift to agents. API-calling agents leverage Large Language Models (LLMs) to interact with software systems via their Application Programming Interfaces (APIs).

For example, by translating natural language commands into precise API calls, agents can retrieve real-time data, automate routine tasks, or even control other software systems. This capability transforms AI agents into useful intermediaries between human intent and software functionality.

Companies are currently using API-calling agents in various domains including:

Consumer Applications: Assistants like Apple’s Siri or Amazon’s Alexa have been designed to simplify daily tasks, such as controlling smart home devices and making reservations.

Enterprise Workflows: Enterprises have deployed API agents to automate repetitive tasks like retrieving data from CRMs, generating reports, or consolidating information from internal systems.

Data Retrieval and Analysis: Enterprises are using API agents to simplify access to proprietary datasets, subscription-based resources, and public APIs in order to generate insights.

In this article I will use an engineering-centric approach to understanding, building, and optimizing API-calling agents. The material in this article is based in part on the practical research and development conducted by Georgian’s AI Lab. The motivating question for much of the AI Lab’s research in the area of API-calling agents has been: “If an organization has an API, what is the most effective way to build an agent that can interface with that API using natural language?”

I will explain how API-calling agents work and how to successfully architect and engineer these agents  for performance. Finally, I will provide a systematic workflow that engineering teams can use to implement API-calling agents.

I. Key Definitions:

API or Application Programming Interface : A set of rules and protocols enabling different software applications to communicate and exchange information.

Agent: An AI system designed to perceive its environment, make decisions, and take actions to achieve specific goals.

API-Calling Agent: A specialized AI agent that translates natural language instructions into precise API calls.

Code Generating Agent: An AI system that assists in software development by writing, modifying, and debugging code. While related, my focus here is primarily on agents that call APIs, though AI can also help build these agents.

MCP (Model Context Protocol): A protocol, notably developed by Anthropic, defining how LLMs can connect to and utilize external tools and data sources.

II. Core Task: Translating Natural Language into API Actions

The fundamental function of an API-calling agent is to interpret a user’s natural language request and convert it into one or more precise API calls. This process typically involves:

Intent Recognition: Understanding the user’s goal, even if expressed ambiguously.

Tool Selection: Identifying the appropriate API endpoint(s)—or “tools”—from a set of available options that can fulfill the intent.

Parameter Extraction: Identifying and extracting the necessary parameters for the selected API call(s) from the user’s query.

Execution and Response Generation: Making the API call(s), receiving the response(s), and then synthesizing this information into a coherent answer or performing a subsequent action.

Consider a request like, “Hey Siri, what’s the weather like today?” The agent must identify the need to call a weather API, determine the user’s current location (or allow specification of a location), and then formulate the API call to retrieve the weather information.

For the request “Hey Siri, what’s the weather like today?”, a sample API call might look like:

GET /v1/weather?location=New%20York&units=metric

Initial high-level challenges are inherent in this translation process, including the ambiguity of natural language and the need for the agent to maintain context across multi-step interactions.

For example, the agent must often “remember” previous parts of a conversation or earlier API call results to inform current actions. Context loss is a common failure mode if not explicitly managed.

III. Architecting the Solution: Key Components and Protocols

Building effective API-calling agents requires a structured architectural approach.

1. Defining “Tools” for the Agent

For an LLM to use an API, that API’s capabilities must be described to it in a way it can understand. Each API endpoint or function is often represented as a “tool.” A robust tool definition includes:

A clear, natural language description of the tool’s purpose and functionality.

A precise specification of its input parameters (name, type, whether it’s required or optional, and a description).

A description of the output or data the tool returns.

2. The Role of Model Context Protocol (MCP)

MCP is a critical enabler for more standardized and robust tool use by LLMs. It provides a structured format for defining how models can connect to external tools and data sources.

MCP standardization is beneficial because it allows for easier integration of diverse tools, it promotes reusability of tool definitions across different agents or models. Further, it is a best practice for engineering teams, starting with well-defined API specifications, such as an OpenAPI spec. Tools like Stainless.ai are designed to help convert these OpenAPI specs into MCP configurations, streamlining the process of making APIs “agent-ready.”

3. Agent Frameworks & Implementation Choices

Several frameworks can aid in building the agent itself. These include:

Pydantic: While not exclusively an agent framework, Pydantic is useful for defining data structures and ensuring type safety for tool inputs and outputs, which is important for reliability. Many custom agent implementations leverage Pydantic for this structural integrity.

LastMile’s mcp_agent: This framework is specifically designed to work with MCPs, offering a more opinionated structure that aligns with practices for building effective agents as described in research from places like Anthropic.

Internal Framework: It’s also increasingly common to use AI code-generating agents (using tools like Cursor or Cline) to help write the boilerplate code for the agent, its tools, and the surrounding logic. Georgian’s AI Lab experience working with companies on agentic implementations shows this can be great for creating very minimal, custom frameworks.

IV. Engineering for Reliability and Performance

Ensuring that an agent makes API calls reliably and performs well requires focused engineering effort. Two ways to do this are (1) dataset creation and validation and (2) prompt engineering and optimization.

1. Dataset Creation & Validation

Training (if applicable), testing, and optimizing an agent requires a high-quality dataset. This dataset should consist of representative natural language queries and their corresponding desired API call sequences or outcomes.

Manual Creation: Manually curating a dataset ensures high precision and relevance but can be labor-intensive.

Synthetic Generation: Generating data programmatically or using LLMs can scale dataset creation, but this approach presents significant challenges. The Georgian AI Lab’s research found that ensuring the correctness and realistic complexity of synthetically generated API calls and queries is very difficult. Often, generated questions were either too trivial or impossibly complex, making it hard to measure nuanced agent performance. Careful validation of synthetic data is absolutely critical.

For critical evaluation, a smaller, high-quality, manually verified dataset often provides more reliable insights than a large, noisy synthetic one.

2. Prompt Engineering & Optimization

The performance of an LLM-based agent is heavily influenced by the prompts used to guide its reasoning and tool selection.

Effective prompting involves clearly defining the agent’s task, providing descriptions of available tools and structuring the prompt to encourage accurate parameter extraction.

Systematic optimization using frameworks like DSPy can significantly enhance performance. DSPy allows you to define your agent’s components (e.g., modules for thought generation, tool selection, parameter formatting) and then uses a compiler-like approach with few-shot examples from your dataset to find optimized prompts or configurations for these components.

V. A Recommended Path to Effective API Agents

Developing robust API-calling AI agents is an iterative engineering discipline. Based on the findings of Georgian AI Lab’s research, outcomes may be significantly improved using a systematic workflow such as the following:

Start with Clear API Definitions: Begin with well-structured OpenAPI Specifications for the APIs your agent will interact with.

Standardize Tool Access: Convert your OpenAPI specs into MCP Tools like Stainless.ai can facilitate this, creating a standardized way for your agent to understand and use your APIs.

Implement the Agent: Choose an appropriate framework or approach. This might involve using Pydantic for data modeling within a custom agent structure or leveraging a framework like LastMile’s mcp_agent that is built around MCP.

Before doing this, consider connecting the MCP to a tool like Claude Desktop or Cline, and manually using this interface to get a feel for how well a generic agent can use it, how many iterations it usually takes to use the MCP correctly and any other details that might save you time during implementation.

Curate a Quality Evaluation Dataset: Manually create or meticulously validate a dataset of queries and expected API interactions. This is critical for reliable testing and optimization.

Optimize Agent Prompts and Logic: Employ frameworks like DSPy to refine your agent’s prompts and internal logic, using your dataset to drive improvements in accuracy and reliability.

VI. An Illustrative Example of the Workflow

Here’s a simplified example illustrating the recommended workflow for building an API-calling agent:

Step 1: Start with Clear API Definitions

Imagine an API for managing a simple To-Do list, defined in OpenAPI:

openapi: 3.0.0

info:

title: To-Do List API

version: 1.0.0

paths:

/tasks:

post:

summary: Add a new task

requestBody:

required: true

content:

application/json:

schema:

type: object

properties:

description:

type: string

responses:

‘201′:

description: Task created successfully

get:

summary: Get all tasks

responses:

‘200′:

description: List of tasks

Step 2: Standardize Tool Access

Convert the OpenAPI spec into Model Context Protocol (MCP) configurations. Using a tool like Stainless.ai, this might yield:

Tool Name Description Input Parameters Output Description Add Task Adds a new task to the To-Do list. `description` (string, required): The task’s description. Task creation confirmation. Get Tasks Retrieves all tasks from the To-Do list. None A list of tasks with their descriptions.

Step 3: Implement the Agent

Using Pydantic for data modeling, create functions corresponding to the MCP tools. Then, use an LLM to interpret natural language queries and select the appropriate tool and parameters.

Step 4: Curate a Quality Evaluation Dataset

Create a dataset:

Query Expected API Call Expected Outcome “Add ‘Buy groceries’ to my list.” `Add Task` with `description` = “Buy groceries” Task creation confirmation “What’s on my list?” `Get Tasks` List of tasks, including “Buy groceries”

Step 5: Optimize Agent Prompts and Logic

Use DSPy to refine the prompts, focusing on clear instructions, tool selection, and parameter extraction using the curated dataset for evaluation and improvement.

By integrating these building blocks—from structured API definitions and standardized tool protocols to rigorous data practices and systematic optimization—engineering teams can build more capable, reliable, and maintainable API-calling AI agents.

[elrohirtheneurodivergent]

I gotta settle a debate between me and two of my siblings:

(I'm making an updated poll, cause I forgot that lots of people listen to entire albums)

[pythonmoth]

cw: violence. torture. waterboarding. hurt/no comfort.

> i haven't written in a long time. it's good to be back.

× framed traitor f!reader x lt ghost. poly tf141.

Part 1

Traitor.

That's what Price thinks as Simon and Soap drag you from the table, nearly choking on your food as they give you no time to understand what's going on.

Alarms ring in your ears as you force the piece of stale bread down your throat, trying to stand on your feet but they're taller than you, so your feet end up dangling, useless. You take a deep breath, your voice shaking as much as you are.

"What's going on? Is this some kind of sick joke?", you ask, looking at Simon, desperate to find an explanation for this other than the anger and torment in his eyes.

Simon doesn't answer. Nobody does. Soap's grip tightens, but he doesn't say anything, his expression hard.

No.

No.

You can tell they are not joking when you realize they're taking you downstairs. Sweat rolls down your face, fear creeping from the base of your neck to your toes, making you snap. You beg them to tell you what's going on, to explain why you're being dragged down there. You kick and struggle, a sob ripped deep from your chest as you start screaming, begging for a reaction. And then, pain.

Tears fill your eyes when it's Simon who hits your stomach with his fist, effectively shutting you up. You can smell the blood from past tortures mixed with bleach, and, distantly, the scent of forgotten wet rags. There's something salty in the air, and that's when you freeze, the pain in your stomach becoming nothing compared to the fear that grows in your chest.

They know you.

You've been with them for nine years. They know your fears.

"No. No. Please. Simon, Johnny— Please, please, please" you beg, sobbing as you can't do anything but go limp and heavy in their grip, doing the best you can to keep them from tying you to the chair. But it's useless.

Stars and colors dance behind your eyes as a fist connects with the side of your chin. You wonder if it would be better if they made you pass out right now. Maybe if you bite your tongue, it could—

"Gag her" Price tells them.

He's trained you for nine years.

He knows you.

You try to bite down on Johnny's fingers as he stuffs your mouth with an old rag, but it's difficult when your senses are unfocused after such a hard punch. The rag wet and disgusting, the scent and the taste making you sob again, shaking your head, your eyes big as you look at Simon.

Please.

Then a wet rag is pressed to your face. You inhale sharply as cold buckets of salty water are dropped right on your face, the cloth making it impossible for you to breathe. Salty water fills your lungs, making you choke and cough around the gagging rag.

You can hear questions, accusations, but you're paralized with fear, with pain and grief.

Grief.

They've been your friends, your family for so long. It's impossible to tell if you'll live through this. It's impossible for you to think of them as anything but monsters.

You know they usually did this with traitors, with enemies when it was necessary.

And you know they never enjoy it.

You've scolded Simon for smoking so late at night, you've had so many drinks next to him when he can't even speak. Simon often flinches awake from nightmares, startling you and then sharing quiet nights side to side.

You know this.

But then Simon hits your face again, taking the rag out of your mouth, and you can't find the love you have for him. It's expelled from your body with each hard cough, with each drop of blood falling from your nose.

"Did you not hear me?" Price demands, his arms crossed. "I'll ask one more time, then."

Smack.

Your chest is heaving, the fear so paralizing you can't even feel each punch as much as you should.

"What did you tell them?" Price continues, not looking one bit anxious for you to answer. He stands in front of you, his feet dry despite the salt burning your lungs.

"I don't know what you're talking about" you manage, looking up at Price, your eyes wide and bloodshot.

With a hard yank on your hair until your head is thrown back again, you're gagged once more, and the rag is pressed to your face. The salty water keeps on filling your lungs, unable to breathe, unable to cough around the gag.

You can't say anything. You truly don't know shit.

Hours later, when it becomes clear you won't speak, Price kicks you across the chest, hard, and the chair flips back.

You're tied up to the chair, exhausted and wet, your lungs burning with salt.

Memories of you as a child, nearly drown to death by your cousins, fill your mind. It had been a good day, until it wasn't.

Simon had held you when you told him, kissed you, and tucked you in for a good night sleep.

Johnny managed to make you crackle when you told him, patting your head, and saying your cousin had awful skills.

Now, there's nothing. Nothing but pain, and the burning in your lungs.

The door springs open, and the three men leave.

Only then do you close your eyes, passing out.

Masterlist | Part 2

buy me a coffee

[stars-and-branches]

why is he so cunty

[rainyramblesscramble]

Can you draw the 141 hugging Gaz (I don't know if you've done something like this before). Just giving Gaz some love, he deserves some love (I feel like a lot of people forget about him, and it makes him sad. I don't want him to be sad🥺😢).

THE WAY MY HEART MELTED SEEING THIS OMG 😭🙏🙏🙏

I just had to colour it. Had to

I completely agree with you—he definitely deserves all the love he can get 🥰🥰🥰

[gomzdrawfr]

Merry Christmas!! they're exchanging gifts by the tree :3

[temeyes]

on your horse muppet, wE ARE LEAVING-

[stygiusfic]

early morning writing hack (real) (it's been working for about a month now):

think about the scene you're going to work on that morning not when you sit down to write, but the previous evening. this is daydreaming but with purpose. think about what might happen and how the characters feel about it. get excited. don't write a single word.

go about your evening normally, doing whatever else you do. your subconscious is a slow cooker and while you do other stuff, it's working on your idea for you.

get up early, like an hour before you'd need to start your day if you were cutting it close. everyone else in the world is snoozing their alarm, so no one can bother you rn. you're free! no one can judge your writing, not even you!

(optional i guess but it really helps me) unless the first few words of your scene are already clear in your mind, warm up. I've abandoned the idea of warm-up drabbles or whatever the hell people recommend. instead, I pull up a story by someone whose writing I love, and I type out a fragment of it in a blank doc, reading the words out loud as I go. this wakes up my writing brain as I become aware of how their prose and dialogue work their magic, when and where they reveal new information, how each detail leads to the next. I'd advise doing this with work that is of high quality and purposeful, so you can learn their tricks, but I'm not the boss of you.

write!!!!!!!

don't stop to judge if it's good or not!! it's too early for that shit!! if the draft sucks you can fix it later but you need the draft done first!!

do stop once yesterday evening's daydreaming prep has run out and you're out of steam. (sometimes the momentum can reveal the next part of the story you hadn't actively considered yet, but don't depend on it.) if you hit a wall where you have no idea how to continue, or it's still too vague to put words down, trying to push through will only bring frustration. and even if you do manage to write a bit more, the chances you'll end up scrapping it later because it doesn't fit are significant. just call it there, you're done.

take a minute to appreciate what you accomplished. you now have words you didn't have yesterday. you won the day, and meanwhile everyone else is still asleep, the absolute losers

if you use a word tracker, go ahead and input your word count for the day. maybe you got a lot done, or maybe you didn't; it's a victory either way. on mornings when I've been struggling, writing and then erasing and writing again, if I'm too pissed off to check the word count I just put down a symbolic number, like 50 words. it may not look like much, but when I look at the month's stats it feels good to have proof that I showed up and did the thing even when it was hard.

now you can start your day. and frankly at this point I don't give a shit how annoying my day is, because I already did the thing I care about getting done, so I'm not going through work resenting every task for stealing brain juice I could've used for writing in the evening. "I'll write when I'm done with work" is the ADHD hubris devil speaking.

and now it's the evening and you're free to daydream again!! and use absolutely zero brain power!! wheee!!

[meltedmush]

I was on a novel binge the past 2 weeks,,,

[mistytwooo]

I want a Ghost fic where it’s Dark stalker ghost, but he’s pathetic, a loser, submissive, and easily manipulated by black dom reader… DONT JUST SIT THERE DIGING IN YOUR NOSE HOLE, START WRITING

[chocokano]

woag

[vintagerobin]

Imagine telling Steph that you forced Cass into a situation where she either had to watch you murder someone right in front of her or else murder you herself in order to stop you, and then expecting Steph to be sympathetic towards you because Cass injured you in a risky but ultimately nonlethal way in a desperate attempt to stop any of that from happening. That's about what expecting Dick to be sympathetic towards Jason for the neck batarang incident feels like to me.

[nekrosmos]

Sharing my thoughts on my 141 Rockstar AU:

Price: Lead singer, rough voice, definitely has a wild attitude but is still a great leader. He’s very politically engaged and has no issues telling people to fuck off. He plays the guitar sometimes too. Nikolai and him are together.

Soap: Lead guitar, extremely energetic, always runs around the stage shirtless, loves the attention, loves to jump into the crowd. He thinks he’s the fans’ favorite (it’s Gaz). Both Gaz and Ghost are his boyfriends.

Gaz: Bassist, also backup singer. Very charismatic, Price’s favorite, the fans love him. He’s very engaged too and does a lot of charity work outside of the band. He’s Soap’s boyfriend.

Ghost: Drummer, always at the back of the stage, in the dark. He wears a mask, fans love to speculate about him. Price has known him for the longest, the two started together before they met Soap and Gaz. Soap’s boyfriend.

Nikolai: Manager, he always follows the band, finding them new opportunities, promoting them, basically always on the phone. Very charismatic. He attends every show, sometimes in the crowd, and loves to watch Price perform. They’ve been together for a bit.

Others:

Farrah, Alex, Rudy, Alejandro : Crew people, always follow the band, have their own unique dynamics. Farrah leads them, Alex is down bad, Alejandro loves to warm up the room before a show, Rudy always has to drag him away eventually.

Laswell: Works at the band’s record company (independent one), has known Price for a long time, she used to perform too in the past but changed path eventually after she got married.

Graves: leads the security at the show. He thinks he’s part of the gang (he isn’t).

Price and Nikolai always found each other after a show, usually while the boys are gone partying. Things usually end up in bed or any adequate surface, as Nikolai cannot keep his hands away from a sweaty Price. Price wears too much leather, too many belts, and always enjoys seeing Nik struggle taking off his clothes. They also often fuck before a show.

When they’re not on tour, the two have a more quiet life, so Price can take care of himself more. Nikolai enjoys both sides of Price.

Soap, Gaz and Ghost usually go out for drinks after a show, often sleeping in hotel rooms they found on the way back rather than in the too small bus beds. Soap and Gaz often attract a lot of attention, which they love and play with, while Ghost put up with it. They'll get out when they feel that Ghost is getting overwhelmed.

[asexualbookbird]

Hey! Hi! I need dental work, a filling repair between two teeth, so I'm opening up simple doodle commissions! Send me a photo of your pet, and I'll turn them into a doodle! I'm not picky about the animal, all critters welcome.

Don't have a pet? No problem! Send me a photo, even an idea, and we can work things out. Your critter doesn't even have to exist.

Whole procedure will be 606$, my goal is 120$ to cover the months phone bill, and I've put down a 25$ deposit for the appointment in September.

I only have cashapp at this time ( $ravencrantz )

I've temporarily opened up tumblr dms, so message me if you're interested! If you want more pet (okay. cat.) doodle examples, check out this tag! For my art in general check out this tag and there's also some things on my other blog @ravencrantz

[noheadcanons-juststories]

Vampire!141 x fledgling!reader, who was found abandoned and starved vampiric abilities: songbird

“His tone is soft and alluring, pretty on the ears. A song that lowers defenses and speaks to the heart rather than the mind. It’s an invitation instead of a mandate.”

•°•°•

Though most vampires are naturally charming, they may be graced with an ability to better attract their prey. Either by sight, smell, or sound, they tend to play mind tricks in order to ease mortals into a sense of safety. Or simply lower their guard.

Although there are a few considered invasive, there is one Sanguine Blessing that merely entices: Songbird.

Songbird (not to be confused with Siren): There are many factors that go into the use of Songbird, from the words, the tone, even the rhythm of how the vampire speaks. This Blessing utilizes sound and its properties to better appeal to the prey's emotions.

Often it is underestimated because of its complexity and rarity, but because it's so deadly is the reason why it is an uncommon Blessing. While Siren simply forces the target to act against their will, Songbird can play into the emotions to persuade or manipulate. In other words, brainwashing.

Even the First realized early on that Songbird was a dangerous ability to have, as its effects are everlasting and most times permanent. Initially, a Sanguine Blessing was passed down to fledglings by a feeding of the master's blood. But by modification via arcane magic, the traits of the fledgling now play a factor instead. Fledglings that gain Songbird are placed under discipline and training for their first five years. (See Sanguine Blessings on pg. V.22|929)

*Excerpt from the Modern Bestiary

first | prev | next Masterlist

Role Call!: @boy-pussyyy | @kawaii-michealmyers | @oaksgrove | @pistachioslife | @chickennuggetuwu

[justanofficeworker]

✨MDNI NSFW✨

I need Soap’s reaction to a near feral partner. Just you’re in that part of your cycle where you just want to be fucked and filled. Like Soap comes home after a real long day and all he wants is to spend the night cuddling his sweet girl. And it’s like the beginning of a horror film. He traverses the hall to your bed room and as he gets closer to the door he just hears your little , pitiful sounds. Just barely there whimpers and whines. For a second he thinks you’re crying, but then he opens the door to find you on your back , 3 fingers plunging into your hot cunt.

You don’t even realize you have an audience until he clears his throat. “I dinae think you’d be this depraved sweetling, did you miss me that much?” He’d smirk down at you , in that way that makes your pussy clench. “ jooooohnny, baby..” you can’t even form the words to beg him for something, anything. Any word you try just devolves into high whines for his touch.

Maybe he’ll be merciful and replace your to small fingers with something bigger and harder or maybe he’ll make you suffer for a bit. Let you make yourself cum, knowing the orgasm wont satisfy you.

Better yet he might let you have your way with his skilled tongue. Wetting his stubble with your sweet juices as he strokes his cock in anticipation for your tight heat.