{"slug": "aichain-agent-plan-act-reflect", "title": "AIchain Agent: Plan, Act, Reflect", "summary": "A developer introduced AIchain Agent, a framework that enables AI models to plan, execute, and reflect on tasks dynamically rather than following a fixed chain of steps. The agent uses an orchestrator model to decide which tools to call and can adapt its plan mid-run based on results, supporting both waterfall and agile execution modes. The project is available on GitHub and aims to handle tasks where the number and order of steps are unknown in advance.", "body_md": "A **Chain** knows every step before it runs. You define step one, step two, step three — and it executes them in order. That works when the problem is well-understood. But what happens when you *don't* know the steps in advance? When the output of one step determines whether you need two more steps or five? When a search returns nothing useful and the whole approach needs to change mid-run?\n\nThat's where **Agent** comes in. It plans, observes what happened, and decides what to do next. The difference between a Chain and an Agent is the difference between a script and thinking.\n\nConsider a task like: \"Find the official documentation for Qdrant, identify its main sections, and summarize each one.\" You don't know ahead of time how many searches you'll need, whether the first URL will be correct, or whether the page content will be structured enough to extract sections from. The number of steps depends on what actually happens at runtime.\n\nIf you try to hard-code this as a Chain, you'll either over-engineer it with branching logic for every edge case, or you'll build something brittle that fails the moment reality doesn't match your assumptions. And it will. Reality always does.\n\nAn Agent handles this naturally. It makes a plan, executes the first step, looks at the result, and adjusts. Maybe it needs one search. Maybe it needs three. The Agent figures that out as it goes.\n\nHere's [the simplest possible Agent](https://github.com/yaitio/aichain/blob/main/examples/13_agent.py) — one model, one tool, one task:\n\n``` python\nimport os\nfrom yait_aichain.models import Model\nfrom yait_aichain.agent import Agent\nfrom yait_aichain.tools import searchPerplexity\n\nagent = Agent(\n    orchestrator=Model(\"claude-sonnet-4-6\", api_key=os.getenv(\"ANTHROPIC_API_KEY\")),\n    tools=[searchPerplexity(api_key=os.getenv(\"PERPLEXITY_API_KEY\"))],\n    max_steps=5,\n    mode=\"waterfall\",\n)\n\nresult = agent.run(\"What are the main differences between Qdrant and Pinecone?\")\nprint(result.output)\nprint(f\"steps={result.steps_taken}  tokens={result.tokens_used:,}\")\n```\n\nThe `orchestrator`\n\nmodel handles planning and reflection — it decides which tool to call, evaluates the result, and determines the next action. The `tools`\n\nlist defines what the agent *can* do. And `max_steps`\n\ncaps how far it can go.\n\nThe `result`\n\nobject gives you three things worth caring about: `.output`\n\n(the final answer), `.steps_taken`\n\n(how many steps actually ran), and `.tokens_used`\n\n(total tokens consumed). Enough to understand what happened and what it cost.\n\nAgents in yait_aichain support two execution modes, and the choice between them shapes how the agent behaves.\n\nIn waterfall mode, the agent builds a complete plan before executing anything. All steps laid out upfront, then run in order. The plan structure is fixed, but reflection still happens between steps — the agent can stop early if the task is already done, or retry a failed step. What it can't do is add new steps or rearrange the remaining ones.\n\nThis gives you predictability. You can look at the plan and know roughly what the agent will do. It's the right choice when the task has a natural structure — \"search, then summarize, then format\" — even if you're not sure whether the search will need a retry.\n\nAgile mode is different. After every step, the agent looks at what just happened and can rewrite all remaining steps. Maybe the first search revealed that the question has two parts, so the agent adds a second search it didn't originally plan. Maybe a step returned exactly what was needed, so the agent skips three planned steps and jumps straight to the final answer.\n\nHere's an adaptive agent with multiple tools:\n\n``` python\nimport os\nfrom yait_aichain.models import Model\nfrom yait_aichain.agent import Agent\nfrom yait_aichain.tools import searchPerplexity, fetchPage, convertToMD\n\nagent = Agent(\n    orchestrator=Model(\"claude-sonnet-4-6\", api_key=os.getenv(\"ANTHROPIC_API_KEY\")),\n    tools=[\n        searchPerplexity(api_key=os.getenv(\"PERPLEXITY_API_KEY\")),\n        fetchPage(),\n        convertToMD(),\n    ],\n    max_steps=8,\n    mode=\"agile\",\n)\n\nresult = agent.run(\n    \"Find the official Qdrant documentation homepage URL, \"\n    \"then fetch that page and tell me what the main sections are.\"\n)\n\nprint(result.output)\nprint(f\"steps={result.steps_taken}  tokens={result.tokens_used:,}\")\n```\n\nThis agent has three tools. `searchPerplexity`\n\nfinds the URL. `fetchPage`\n\nretrieves the raw page content. `convertToMD`\n\nstrips the HTML down to Markdown so the model can read the structure cleanly. The agent decides on its own which tool to call at each step, and it can change its plan based on what each tool returns.\n\nThat flexibility isn't free. The execution path is less predictable, and the agent may burn more tokens exploring approaches that don't pan out.\n\n**Use waterfall when the task has a known shape. Use agile when it doesn't.**\n\nAn agent without `max_steps`\n\nis an infinite loop waiting to happen.\n\nWithout a hard cap, the agent keeps planning and executing until it exhausts the model's context window or burns through your token budget. In development, that's an awkward wait and a surprising bill. In production, it's an outage.\n\n```\n# Missing max_steps. The agent runs until something breaks.\nagent = Agent(\n    orchestrator=Model(\"claude-sonnet-4-6\", api_key=os.getenv(\"ANTHROPIC_API_KEY\")),\n    tools=[searchPerplexity(api_key=os.getenv(\"PERPLEXITY_API_KEY\"))],\n    mode=\"agile\",\n)\n```\n\nAlways set `max_steps`\n\n. For a single-tool task like \"search and summarize,\" 5 steps covers one search, a possible retry, and the synthesis pass with room to spare. For multi-tool workflows — search, fetch, convert, analyze — 8 to 10 reflects the realistic step count without giving the agent room to spiral.\n\nYou should also check whether the agent hit its ceiling before finishing:\n\n```\nif result.steps_taken == max_steps:\n    # The agent ran out of steps before completing the task.\n    # Log, retry with a higher limit, or surface an error to the user.\n    print(f\"Warning: agent hit max_steps={max_steps}. Output may be incomplete.\")\nelse:\n    print(result.output)\n```\n\nDon't skip this check. An agent that hit `max_steps`\n\nmay return a plausible-looking but incomplete answer, and you won't know unless you look.\n\nIf you already know the steps, use Chain. It's deterministic, cheaper, and easier to debug. Every time.\n\nUse Agent when the number or nature of steps can't be determined before execution begins — when the task requires reacting to intermediate results, when the path from question to answer isn't a straight line.\n\nMy practical heuristic: if you can draw the workflow on a whiteboard before writing code, that's a Chain. If you'd need to draw multiple possible workflows with \"it depends\" arrows between them, that's an Agent.\n\nFor reference, here's what you can configure:\n\n```\nAgent(\n    orchestrator: Model,        # required — plans and reflects\n    executors:    list[Model],  # optional — cheaper models for tool-call steps\n    tools:        list,         # optional — tools available to the agent\n    mode:         str,          # \"waterfall\" | \"agile\"  (default: \"waterfall\")\n    max_steps:    int,          # hard cap on execution depth\n)\n```\n\nThe `executors`\n\nparameter lets you assign a cheaper or faster model to run individual tool-call steps while keeping a more capable model as the orchestrator:\n\n``` python\nimport os\nfrom yait_aichain.models import Model\nfrom yait_aichain.agent import Agent\nfrom yait_aichain.tools import searchPerplexity, fetchPage, convertToMD\n\nagent = Agent(\n    orchestrator=Model(\"claude-sonnet-4-6\", api_key=os.getenv(\"ANTHROPIC_API_KEY\")),\n    executors=[Model(\"gemini-2.5-flash\", api_key=os.getenv(\"GOOGLE_API_KEY\"))],\n    tools=[\n        searchPerplexity(api_key=os.getenv(\"PERPLEXITY_API_KEY\")),\n        fetchPage(),\n        convertToMD(),\n    ],\n    max_steps=8,\n    mode=\"agile\",\n)\n```\n\nThe orchestrator handles the reasoning-heavy work — deciding what to do next, evaluating results, writing the final answer. The executor handles the mechanical steps in between: calling a tool and passing the output back. A capable model where it matters, a faster cheaper one where it doesn't. That split alone can meaningfully reduce costs on longer workflows.", "url": "https://wpnews.pro/news/aichain-agent-plan-act-reflect", "canonical_source": "https://dev.to/yait/aichain-agent-plan-act-reflect-2n71", "published_at": "2026-06-20 10:02:00+00:00", "updated_at": "2026-06-20 10:06:35.953794+00:00", "lang": "en", "topics": ["ai-agents", "large-language-models", "developer-tools", "artificial-intelligence"], "entities": ["AIchain", "Qdrant", "Pinecone", "Perplexity", "Anthropic", "Claude"], "alternates": {"html": "https://wpnews.pro/news/aichain-agent-plan-act-reflect", "markdown": "https://wpnews.pro/news/aichain-agent-plan-act-reflect.md", "text": "https://wpnews.pro/news/aichain-agent-plan-act-reflect.txt", "jsonld": "https://wpnews.pro/news/aichain-agent-plan-act-reflect.jsonld"}}