Chatbot: question -> model -> answer Workflow: step 1 -> step 2 -> step 3 (YOU fixed the sequence; the model fills in individual steps) Agent: goal -> [ think -> act (tool) -> observe ] -> repeat -> done (the MODEL chooses the sequence) 

 ┌──────────────────────────── AGENT RUNTIME (your code) ────────────────────────────┐ │ │ Goal / │ ┌──────────────┐ decides ┌──────────────┐ executes ┌──────────────┐ │ user request ─>│ │ INSTRUCTIONS │ ──────────> │ MODEL │ ──────────> │ TOOLS │ ──> World │ │ + CONTEXT │ │ (LLM "brain")│ │ (functions, │ (APIs, DBs, │ └──────────────┘ <────────── └──────────────┘ <────────── │ APIs, code) │ <── files, web) │ ^ observations results └──────────────┘ │ │ │ │ │ │ ┌──────┴───────┐ ┌──────────────┐ ┌──────────────┐ ┌──────┴───────┐ │ │ │ MEMORY │ │ LOOP CONTROL │ │ GUARDRAILS / │ │ OBSERVABILITY │ │ │ │ (short/long) │ │ budgets, stop │ │ POLICY ENGINE │ │ traces, audit │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ │ └────────────────────────────────────────────────────────────────────────────────────┘ 

MODEL The reasoning engine. Chooses the next action from the context it is given. INSTRUCTIONS The system prompt: role, goals, rules, constraints, how to use tools, when to stop or ask. TOOLS The agent's "hands" — functions it can call (Sections 2-3). MEMORY What it knows: the working context for this run, plus anything retrieved from longer-term storage (Section 5). LOOP CONTROL Deterministic code that runs the cycle and enforces step/token/time budgets and stop conditions. GUARDRAILS Policy checks around tool calls and outputs — authorization, validation, approvals (Sections 9-10). OBSERVABILITY Traces of every step, for debugging, audit, and evaluation (Section 11). ENVIRONMENT The world the agent acts on: systems, data, other agents, people. 

using Microsoft.Extensions.AI; public record AgentBudget(int MaxSteps = 8, int MaxTokens = 50_000, TimeSpan? MaxDuration = null); public sealed class Agent(IChatClient llm, IReadOnlyList<AIFunction> tools, IToolPolicy policy, ILogger<Agent> log) { public async Task<AgentResult> RunAsync(string goal, string instructions, AgentBudget budget, CancellationToken ct) { var messages = new List<ChatMessage> { new(ChatRole.System, instructions), new(ChatRole.User, goal) }; var options = new ChatOptions { Tools = [.. tools], ToolMode = ChatToolMode.Auto, Temperature = 0.2f, MaxOutputTokens = 800 }; var deadline = DateTime.UtcNow + (budget.MaxDuration ?? TimeSpan.FromMinutes(2)); int tokensUsed = 0; for (int step = 1; step <= budget.MaxSteps; step++) // HARD cap: steps { ct.ThrowIfCancellationRequested(); if (DateTime.UtcNow > deadline) return AgentResult.Stopped("time budget exceeded", messages); // HARD cap: time // THINK: ask the model what to do next ChatResponse response = await llm.GetResponseAsync(messages, options, ct); tokensUsed += (int)(response.Usage?.TotalTokenCount ?? 0); if (tokensUsed > budget.MaxTokens) return AgentResult.Stopped("token budget exceeded", messages); // HARD cap: tokens messages.AddRange(response.Messages); var calls = response.Messages.SelectMany(m => m.Contents).OfType<FunctionCallContent>().ToList(); if (calls.Count == 0) return AgentResult.Completed(response.Text, messages); // no tool requested: the agent considers itself done // ACT + OBSERVE: execute each requested tool through the policy gate foreach (FunctionCallContent call in calls) { object? result = await ExecuteAsync(call, ct); messages.Add(new ChatMessage(ChatRole.Tool, [new FunctionResultContent(call.CallId, result)])); log.LogInformation("Step {Step}: {Tool} -> {Outcome}", step, call.Name, Summarize(result)); } } return AgentResult.Stopped("step limit reached", messages); } private async Task<object?> ExecuteAsync(FunctionCallContent call, CancellationToken ct) { AIFunction? tool = tools.FirstOrDefault(t => t.Name == call.Name); if (tool is null) return $"Error: there is no tool named '{call.Name}'."; // GUARD: policy decides allow / deny / needs approval — in CODE, not in the prompt ToolDecision decision = policy.Evaluate(call.Name, call.Arguments); if (decision == ToolDecision.Deny) return "This action is not permitted."; if (decision == ToolDecision.RequireApproval) return "This action requires human approval and was not executed."; try { return await tool.InvokeAsync(new AIFunctionArguments(call.Arguments), ct); } catch (Exception ex) { log.LogWarning(ex, "Tool {Tool} failed", call.Name); return "The tool failed. Try a different approach or report the problem."; } } private static string Summarize(object? result) => result?.ToString()?[..Math.Min(80, result.ToString()!.Length)] ?? "null"; } public enum ToolDecision { Allow, Deny, RequireApproval } public interface IToolPolicy { ToolDecision Evaluate(string toolName, IDictionary<string, object?>? arguments); } public record AgentResult(string Status, string? Answer, string? Reason, IReadOnlyList<ChatMessage> Transcript) { public static AgentResult Completed(string answer, IReadOnlyList<ChatMessage> t) => new("completed", answer, null, t); public static AgentResult Stopped(string reason, IReadOnlyList<ChatMessage> t) => new("stopped", null, reason, t); } 

REACT-STYLE LOOP The loop above: reason about the next step, act, observe, repeat. Simple and flexible; the default for tool-using agents. PLAN-AND-EXECUTE First produce a plan (a list of steps), then execute the steps — possibly with replanning if something fails. More predictable and auditable than step-by-step improvisation (Section 4). REFLECTION After producing a result, a critique pass (same or different model) checks it and the agent revises. Improves quality on tasks with checkable criteria, at the cost of extra calls. ROUTER / TRIAGE A first step classifies the request and sends it to the right specialist or workflow. WORKFLOW + AGENT A deterministic workflow that invokes a bounded agent for just the open-ended step — often the most reliable production design. 

Every loop iteration resends the growing transcript. Agents therefore live or die by what is IN the context: - TOOL RESULTS dominate token use. Return small, relevant results; truncate and summarize big ones. - COMPACT as you go: summarize completed sub-tasks and drop raw tool output the agent no longer needs. - KEEP a short, structured SCRATCHPAD (goal, plan, progress, key facts) the agent updates, instead of relying on the whole raw history. - ISOLATE sub-tasks: delegate to a sub-agent with a fresh, minimal context and take back only its summary (Section 7). - Quality DEGRADES as context fills with noise (see LLM Application Development, Section 6) — lean contexts make better agents and cheaper ones. 

FIXED WORKFLOW Steps hard-coded; model used inside steps. Predictable, testable, cheap. ROUTED WORKFLOW Model chooses WHICH fixed workflow to run. Still predictable within each branch. BOUNDED AGENT Model chooses steps, within tight limits. Flexible; needs budgets and guardrails. OPEN-ENDED AGENT Model chooses steps, tools, even sub-goals. Most capable, least predictable, riskiest. Move right only as far as the problem demands. Most production value comes from the left half. 

Kinds of tools: READ / RETRIEVE search documents, query a database, fetch a page, read a file (low risk) COMPUTE run code, do math, transform data (risk depends on sandboxing) WRITE / ACT create a ticket, send an email, update a record, deploy, pay (HIGH risk — gate these) COMMUNICATE message a human or another agent, ask for clarification (low-medium risk) META "think" / scratchpad tools, plan updates, task completion signals (low risk) HOSTED / BUILT-IN provider-run tools: web search, code interpreter, file search (provider-specific) MCP tools exposed by Model Context Protocol servers (see security, Section 10) 

CLEAR NAMES AND DESCRIPTIONS The description is the tool's entire user manual for the model. State what it does, when to use it, when NOT to, what each parameter means, and its limits. Vague descriptions cause wrong calls and missed calls — more than any prompt tweak. RIGHT GRANULARITY Not too fine (search_by_id, search_by_name, search_by_email, ... which one?) and not too coarse (do_everything(action, payload)). One tool per meaningful capability. SIMPLE, TYPED PARAMETERS Use enums for closed sets, clear formats for dates and IDs, and as few parameters as possible. Every optional parameter is another chance for a wrong value. SMALL, USEFUL RESULTS Return what the agent needs, in a readable form, with pagination or caps for large data. Raw 5,000-row dumps waste context and confuse the model. HELPFUL ERRORS "No customer found with email x@y.com. Try searching by name." teaches the agent how to recover. A bare stack trace — or a swallowed error — causes loops and hallucinated success. IDEMPOTENT WHERE POSSIBLE Retried or repeated calls shouldn't double-charge or double-send. Accept an idempotency key for side-effecting tools. READ VS. WRITE SEPARATION Distinct tools for reading and for changing state, so policy can treat them differently. LEAST PRIVILEGE Each tool does the minimum necessary, scoped to the current user's permissions. FEW TOOLS PER AGENT Selection accuracy falls as the toolset grows. Give each agent a focused set; for large catalogs, load tools dynamically (tool search/retrieval) or split across specialist agents. 

[Description("Searches the customer's support tickets. Use it to find a ticket by topic or keyword. " + "It returns at most 5 matches, newest first. To read a specific ticket, use get_ticket with its id.")] public async Task<string> SearchTicketsAsync( [Description("Keywords describing the problem, e.g. 'refund not received'")] string query, [Description("Only include tickets with this status. Allowed: open, closed, any")] TicketStatus status = TicketStatus.Any, CancellationToken ct = default) { var hits = await tickets.SearchAsync(user.Id, query, status, top: 5, ct); // scoped to the authenticated user in CODE return hits.Count == 0 ? "No matching tickets. Try different keywords, or status 'any'." : string.Join("\n", hits.Select(t => $"#{t.Id} [{t.Status}] {t.Title} ({t.UpdatedOn:d})")); } public enum TicketStatus { Any, Open, Closed } 

1. You send: messages + function DEFINITIONS (name, description, parameter schema) 2. Model sends: a function CALL { name: "search_tickets", arguments: { "query": "refund", "status": "open" } } (FinishReason = ToolCalls) — possibly SEVERAL calls at once 3. You run: the function(s), through your policy gate 4. You send: the conversation + each function's RESULT (matched to the call's id) 5. Model sends: another call — or the final answer 

var searchTool = AIFunctionFactory.Create(tools.SearchTicketsAsync, name: "search_tickets"); var getTool = AIFunctionFactory.Create(tools.GetTicketAsync, name: "get_ticket"); var options = new ChatOptions { Tools = [searchTool, getTool], ToolMode = ChatToolMode.Auto }; 

ToolMode Auto The model decides whether to call a tool. ToolMode RequireAny The model MUST call a tool (useful for forced extraction or routing). ToolMode None Tools are described but cannot be called (e.g. for a final summarization turn). PARALLEL TOOL CALLS A model may request several independent calls in one turn (look up three orders at once). Execute them concurrently if they're independent and safe — but NEVER parallelize calls that depend on each other or that mutate the same state, and cap concurrency. 

WRONG TOOL / WRONG ARGUMENTS Usually vague descriptions, overlapping tools, or too many tools. Fix the tool design first. HALLUCINATED ARGUMENTS The model invents an ID or value it was never given. Validate against reality ("order 99999 not found") and return a helpful error. MISSING REQUIRED INFORMATION The agent should ASK the user rather than guess. Give it a way to: an ask_user tool, or an instruction to respond with a clarifying question when required information is missing. ARGUMENT INJECTION Arguments are model output steered by untrusted text. Validate them like user input: parameterized queries, allow-lists, range checks — never string-concatenate into SQL, shell commands, or URLs. RUNAWAY LOOPS Repeated identical failing calls. Detect repeats; cap steps; return different error guidance. 

public sealed class ToolPolicy(ICurrentUser user) : IToolPolicy { private static readonly HashSet<string> ReadOnly = ["search_tickets", "get_ticket", "search_docs"]; private static readonly HashSet<string> Sensitive = ["issue_refund", "send_email", "close_account"]; public ToolDecision Evaluate(string toolName, IDictionary<string, object?>? args) { if (ReadOnly.Contains(toolName)) return ToolDecision.Allow; if (Sensitive.Contains(toolName)) return ToolDecision.RequireApproval; // a human confirms (Section 9) return ToolDecision.Deny; // default DENY: unknown tools are never allowed } } 

Goal: "Find the delivery date for order 10482, tell the customer, and set a reminder the day before." Step 1: get_order(10482) -> shipped, ETA Friday Step 2: draft_email(...) -> draft created Step 3: send_email(...) -> [needs approval] Step 4: create_reminder(Thursday) -> done Step 5: final answer 

public record PlanStep(int Id, string Description, string ToolName, string ArgumentsJson); public record Plan(List<PlanStep> Steps); // 1. PLAN — ask the model for a structured plan; the model does NOT execute anything yet ChatResponse<Plan> planResponse = await llm.GetResponseAsync<Plan>( [ new(ChatRole.System, $"Create a plan using ONLY these tools: {string.Join(", ", allowedTools)}. " + "Each step must name exactly one tool. Keep the plan as short as possible."), new(ChatRole.User, goal) ], ct); Plan plan = planResponse.Result; // 2. VALIDATE — in CODE: allowed tools only, sane step count, no forbidden combinations, human review if sensitive if (plan.Steps.Count > 10 || plan.Steps.Any(s => !allowedTools.Contains(s.ToolName))) throw new InvalidOperationException("Plan rejected."); if (plan.Steps.Any(s => Sensitive.Contains(s.ToolName))) await approvals.RequestPlanApprovalAsync(plan, ct); // show the whole plan to a person first // 3. EXECUTE — your code runs the steps deterministically; the model is used only for steps that need judgment foreach (PlanStep step in plan.Steps) await executor.RunAsync(step, ct); 

Benefits: the plan is an artifact you can LOG, REVIEW, TEST, and APPROVE; execution is deterministic; costs are predictable; and the model can't improvise an action nobody reviewed. Costs: less adaptive when reality diverges from the plan — so add REPLANNING: on a failed or surprising step, ask the model for a revised plan (bounded to N replans), re-validate, and continue. 

DECOMPOSITION Split a large goal into sub-goals, each solved separately (by one agent over time or by several). PLAN-AND-EXECUTE As above: plan once, run, replan on failure. REFLECTION / CRITIQUE After a step or at the end, check the output against criteria and fix problems. SELF-VERIFICATION Have the agent (or a separate checker) confirm the goal was achieved by inspecting the actual state — "did the ticket really get created?" — rather than trusting the agent's claim. CLARIFY FIRST If the goal is ambiguous or missing information, ask the user BEFORE planning. Most bad agent runs begin with a misunderstood goal. BUDGETED PLANNING Cap the number of steps, replans, and tokens; stop and report rather than flail. 

If each step is 95% reliable, a 10-step task succeeds only about 60% of the time (0.95^10 ≈ 0.60). At 90% per step, 10 steps succeeds about 35% of the time (0.90^10 ≈ 0.35). Implications: - FEWER STEPS beat clever steps. Shorten plans, combine tools, and move deterministic work into code. - VERIFY along the way, not just at the end, so errors are caught before they compound. - Make steps INDEPENDENTLY RECOVERABLE (idempotent, checkpointed) so a failure doesn't restart everything. - Evaluate end-to-end success, not just per-step accuracy (Section 11). 

WORKING MEMORY (context) The current run's transcript, scratchpad, and retrieved facts. Lives in the context window; bounded and expensive. Managed by compaction and summarization. SHORT-TERM / SESSION The ongoing conversation or task thread, persisted so the agent can resume (a thread or conversation store keyed by user and conversation). EPISODIC MEMORY Records of past runs — what was tried, what happened, what worked or failed. Lets an agent avoid repeating mistakes and recall "last time we did X for this customer." SEMANTIC (LONG-TERM) Durable facts and knowledge — user preferences, entities, domain knowledge — stored (often with embeddings) and retrieved by relevance. This is RAG applied to the agent's own knowledge. PROCEDURAL MEMORY Reusable "how to" knowledge: instructions, playbooks, skills, or learned guidelines the agent loads when relevant. Often implemented as versioned prompt/skill files rather than a database. 

Source：https://dev.to/rhuturaj_takle/ai-agents-18l
My favorites