Skip to content

AI agents ​

Agents are AI assistants you attach to a node, a connection between two nodes, or the whole canvas, to chat about that part of your dataflow. A change an agent makes to your dataflow lands at once, as your own edit does, and you can undo it from the chat.

An agent is an autonomous runtime with a goal (its instruction), its own tools and model, and a memory (the conversation of each chat). A skill tells an agent how to do a specific task, such as writing a Map Editor node's edits: instructions, procedural knowledge, reference facts and starter templates, in a SKILL.md file. A skill does nothing on its own, and an agent reads one when a task needs it. One skill serves many agents, and an agent uses many skills.

Choose the provider and model ​

Agents answer with an LLM configuration: a provider, its key and a model, which you set up in API Settings. API Settings has two tabs, API keys and Agent configuration.

  1. Get an API key from the provider: OpenAI, Anthropic or Gemini. The form links to the same pages (Get your OpenAI key, for example). A model you run yourself, such as one in Ollama or LM Studio, may need no key.
  2. Open API Settings from the top bar. On the Projects and catalog pages it opens the settings page; on the canvas and the dashboard it opens as a drawer on the right, and your dataflow stays open.
  3. On the API keys tab, click + (Add configuration) at the end of the table's header.
  4. In Kind, choose Language model.
  5. Give it a Label, and pick the Provider: OpenAI, Anthropic, Gemini, or Custom for any OpenAI-compatible endpoint, such as a model you run yourself (Custom asks for a Base URL).
  6. Paste the API key, and choose the Model: Fetch models suggests what the endpoint serves, or type a model name.
  7. Click Add configuration. The configuration's row shows in the list, with Key saved under its name when you gave a key. Make this my default is ticked on your first configuration, so it becomes your default.

You can keep several configurations, for different providers or models. A row of yours ends with x (Remove) and a pencil (Edit). On the Agent configuration tab, Default for my agents picks your default, and Each agent picks what each agent runs on; Follows my default keeps an agent on your default. Curio does not bill agent runs: the provider charges whoever's key is used.

When whoever runs the server offers models of its own, the API keys tab starts with a read-only Curio row for each of its endpoints, with Provided by and the endpoint's name under it and the endpoint's models in its Details. You use those models with no key of your own:

  1. Open API Settings and click the Agent configuration tab.
  2. In Default for my agents, pick a model under Curio · and the endpoint's name. Curio's default, first in the list, is the model marked Curio default on the API keys tab, which every account answers on until it picks another.
  3. To give one agent a model of its own, pick it in that agent's list under Each agent.
  4. The choice is saved at once, and Answering now names the endpoint and the model.

On a server started with --deploy, guests cannot add a configuration or pick a model, and answer on Curio's default.

Screenshot to recordnew:apisettings
API Settings: every key in one list on the API keys tab, and the model each agent runs on under Agent configuration.

Add an agent to a dataflow ​

On the canvas, click Agent Catalog in the top bar, or open the Agent Catalog dropdown in the Tools panel and click Browse Agent Catalog +. The drawer has two tabs: Browse all, and In project for the agents this dataflow has. In the catalogs, a project is one of your saved dataflows.

Every dataflow starts with the agents Curio comes with, already in the Tools panel's Agent Catalog dropdown. To add another, click Add to project and confirm. An agent that relies on others says so on its button, as in Add to project (+1 required), and the agents it needs are added with it. Added agents appear in the same dropdown.

Agent Catalog, in the top bar of the Projects page, lists the agents for your whole account. Click one to read about it; Add to all projects adds it to every project you have and to new ones; Remove from all projects takes it out of every project you have and of new ones, and Curio does not add it back. Import agent adds one you wrote yourself. Importing a newer version of an agent you have replaces yours, a new major version is added beside the old one, and the same or an older version is refused. When the server allows it, Publish shares an agent you imported with everyone on that server, and whoever added it gets a newer version of the same major the next time they add the agent to a dataflow.

Attach it to your work ​

Adding an agent makes it available; attaching it puts it to work. Drag it from the Agent Catalog dropdown and drop it:

  • on a node, to work with that node's code and output (a badge appears under the node)
  • on a connection, to work with what flows between two nodes (a badge appears on the connection)
  • on empty canvas, to work with the whole dataflow (it joins the bar at the top of the canvas)

An agent only accepts the targets it was made for. Each attachment has its own conversation, and one agent can be attached in several places. Once an agent is attached, the bar at the top also shows a Goal field: say what the dataflow is for, and the agents that read it take it into account. To detach an agent, hover its badge and click ✕, which also deletes its conversation.

Chat and changes ​

Click a badge to open the agent's chat. The header says what the agent is attached to, the arrows step through your attached agents, and you can rename or clear the conversation. The first message is the agent's instruction, which the pencil lets you edit. Type in Message this agent… and send.

The agent answers on the Curio server: closing or reloading your tab does not stop it, and its reply is in the chat when you come back. A chat answers one message at a time. A message sent while it answers waits under the last message, marked Waiting its turn, and Withdraw takes it back until then. Stop, under a reply being written, stops the agent at its next step: what it wrote and the changes it made stay, and the reply says who stopped it, such as Stopped by Ana after 12s. The chats of different attached agents answer at the same time.

What an agent does depends on the agent: explain or debug a node, write node code, find datasets (including in the open data portals of the Discovery Catalog), plan or build a whole dataflow, suggest connections and packages, or review your work. A change it makes, to a node's code or settings, a new node or a plan, lands at once, for everyone in the dataflow, as your own edit does. The chat shows each change as a card with Undo, which puts back what the change replaced:

  • a node's code as it was;
  • a new node taken away, with its connections;
  • settings back to their old values;
  • the dataflow as it was before a plan, with the nodes the plan removed and their connections.

Undo is your own change. When someone changed what it would put back after the agent did, Undo is refused, saying who, and nothing changes.

An install changes your account, so it waits for you: a package, a package draft, a dataset, a download from the Discovery Catalog or an agent added to the dataflow appears as a review card. Nothing installs until you click Apply, and Dismiss drops it.

Clip to recordtour:agentrun
An agent's chat opens from its badge on a node, a question about the node is sent, and the answer appears in the chat.

What agents work with ​

Agents build with Curio's own nodes, functions, catalogs and chips, as you do, and read what you made with them.

An agent uses only what you have. The code it writes reads your Data Catalog's datasets, runs the models you added and uses the keys you saved. It calls only the functions and imports only the modules its node gets. For any other model, the agent asks you to add it in the Model Catalog.

An agent that writes code reads what the dataflow can use: its datasets and models, and the names of your Node code keys, never their values. When it writes a node's code, it also reads the node's template: its description, its starter and the functions its code can import.

An agent that reads the dataflow also sees how each node is set, such as a Data Pool's modes, a Simple View's image column, a Spatial Join's operation and each widget's value, and which nodes are tiles of the dashboard. The Node Builder and the Dataflow Builder set these on the nodes they add, and change them on a node you have: ask, for example, to make a pool merge with AND, or to use within instead of intersects. The change's card names each setting as the node's own controls do, such as Image column: overlay_url, and the change sets the node as picking it there would.

An agent writing a node beside a Map Editor node reads its edits. Asked for a scenario of another project, the Dataflow Builder finds it in your Scenario Catalog and names it and its project for you to drag in.

A change an agent makes to a node's code is an entry named after the agent in the node's Provenance drawer, and a node an agent adds with its code starts with one. Open it to see when it was made and the code it left, and put that code back as you would a run's. The Node Builder and the Dataflow Builder read these histories, so you can ask either what changed in a node since a run.

The Node provenance drawer of a Python node named Years, with one entry, Node Builder
The Provenance drawer of a Python node after the Node Builder changed its code: entry 1, named after the agent.

An agent at work ​

While an agent works on the dataflow, on a chat message, a task another agent hands it, a Solve or Build & validate, everyone with the dataflow open sees it as one more person (Collaboration):

  • The dock at the top of the canvas has a chip for it, which says who asked it, the nodes it is writing and the skills it is using, such as Node Builder (asked by Ana), editing Map Editor, using map-edits.
  • Its cursor shows only while it drags on the canvas: a new node from its tile in the tool rail or a card in a catalog drawer, a node to a new place, or a card onto a node. Its other changes land with no cursor.
  • Before it writes a node, it waits while someone else is in the node; after 30 seconds it gives up, and nothing changes. While it writes, the node shows its code or spec, or its Widgets tab for a widget's value, then goes back to the tab it showed.
  • It does one thing at a time: a plan's nodes are dragged in one after another, then its connections land. When someone removes a node the plan joins meanwhile, the plan stops there, and its card says what was left undone.

Each change it makes is also a version in the dataflow's history, named after the agent and who asked it, such as Node Builder, asked by Ana.

With the editors you invite ​

The editors you invite work with the dataflow's agents as you do: they add and attach agents, chat and run Solve. You and every editor read and write the same chat of each attached agent, and a message someone else wrote shows their name above it. A reply shows in each of your tabs as it is written, a message waits its turn behind anyone's, only whoever sent a waiting message can withdraw it, and any of you can stop a reply. An editor's chats answer with your model and key, as your API Settings choose them, and name only the editor's own saved keys, never yours. An install an agent asks for in an editor's chat waits for you: its card reads Waits for the dataflow's owner to review it, and you review it in the same chat. Anyone else who opens the dataflow's link sees an agent at work in the dock, but not its badges or its chats.

Skills ​

The Skill Catalog lists every skill your agents can read, each a SKILL.md in the Agent Skills format: the ones Curio ships, your own, published ones and those of packages, with what each tells an agent. This section is about an agent's own skills: how they reach its runs, and how you change them.

How a skill reaches a run ​

  • Always on: every call holds the core skills.
  • Handed for what a run writes: a run that writes or checks a node is handed the skills that serve that kind of node, such as map-edits for a Map Editor node, and a run that reads the whole dataflow is handed those of its nodes and features, such as scenarios for a dataflow with scenario boxes. A chat on a node holds the skills of that kind of node, and a chat or a mode holds the procedures it follows from its first message, such as reuse-first in the Node Builder's chat.
  • Loaded by the agent: in chat, an agent lists its other skills by name and description, and loads one with its skill.read tool when a task matches it. A skill a chat loaded stays for the rest of its conversation.
  • Named by you: type / at the start of a message to list the chat's skills, then pick one or keep typing its name, as in /map-edits remove the two tallest towers. The run gets the skill with your message, and the conversation keeps it.
  • Asked for in your words: a skill can name words that hand it to a chat, and a message that holds one gets the skill the same way. scenarios comes with a message that says scenario, scenarios, what if or what-if, as in "What if the speed limit dropped to 20?". A word counts whole and in any case, and only in what you type, never in a task one agent hands another.

A line under each chat reply, Skills:, names the skills its run held or loaded, apart from the core skills. Hover a name to see how the run got it: handed for the chat's node or instruction, named with / in the message, handed for words in the message, kept from earlier in the chat, or loaded for this reply.

Add and remove skills ​

View details, on an agent's card in the Agent Catalog or beside it in the Tools panel's Agent Catalog dropdown, opens the agent's details. Their Skills section lists the skills the agent holds:

  • Add skill gives the agent one of the skills it does not hold, which then reads Added by you.
  • Remove takes a skill away.
  • Restore, once you have changed the list, brings back the skills the agent ships with.

Click a skill's name to open its details from the Skill Catalog over the agent's.

A change is for your account: it covers every project from the agent's next run, its chat and its modes alike. The core skills read Every call. A skill that the agent's chat instruction, one of its modes or a call another agent asks it for holds as its own reads Always in chat, Always for and the mode's name, or Always when another agent asks: the Dataset Finder's catalogs reads Always for Find datasets. Those have no Remove. A guest on a hosted Curio sees an agent's skills and changes none.

To write a skill of your own, and an agent that reads it, see Add skills and agents.

In chat, tools, modes and skills ​

Curio describes what an agent does and knows in four words:

  • In chat: what you can ask an agent where you dropped it.
  • Tools: the actions an agent takes during a chat, such as reading the dataflow, searching the web, adding a node or asking to install a package. A change to your dataflow lands at once, as your own edit does, and you can undo it from the chat; an install waits for your review.
  • Modes: what another agent, Solve or the agent itself can ask it to do. A mode runs as a separate call with no tools, on evidence Curio gathers for it. You never chat with a mode.
  • Skills: what tells an agent how to do a specific task, such as writing a Map Editor node's edits. See Skills.
AgentIn chatToolsModes (who asks)Skills
ResearcherExplains a node or the dataflow, diagnoses errors, helps define what to build, answers web questions as notes, checks factsRead the dataflow and a node's last run; search and read the web; place notes as Note nodes; propose a notes packageNotes from search results (Dataflow Builder); Check a fact (Node Builder, Dataset Finder, Dataflow Builder)The feature skills, loaded in chat when a task needs one; reuse-first, fact-checking and research-notes from its chat's first message, and each mode is handed its own
Node BuilderBuilds a node, rewrites a node's content, changes a node's settings, suggests nodes for a connection, finds or writes node typesRead the dataflow, a node's last run and its history; search the Data and Model Catalogs; add a node, write a node's content or change its settings; propose a package install or a package draftWrite a node's content (Node Builder, Dataflow Builder, Solve); Recommend packages (Dataflow Builder); Write a package (Node Builder, Researcher, Dataflow Builder)The feature skills, loaded in chat; reuse-first and data-sources from its chat's first message; its modes are handed those of what they write and their own
Dataflow BuilderPlans a whole dataflow, then solves its nodesRead the dataflow, runs and node histories; search the Scenario Catalog; make a plan, add a node or change a node's settings; propose a package draft; read worked examplesNoneThe feature skills, reuse-first and data-sources, loaded in chat
Dataset FinderFinds datasets in the Data Catalog and in portalsSearch the catalog and portals; propose a downloadFind datasets (Node Builder, Dataflow Builder, Solve)catalogs and data-sources, loaded in chat; catalogs handed to Find datasets

How an agent picks what to run ​

Every call to the model is the shared preamble, the skills the call holds and one instruction. A message you type goes to the agent's chat instruction, and in that same call the model decides what you asked for and which tools to use. A mode runs only when something asks for it, as a separate call.

For example, you ask the Node Builder on a node to "turn this into a bar chart":

  1. Your message goes to the Node Builder's chat, which reads the node and asks for its content mode.
  2. The content mode writes the chart in a separate call, with no tools, from the node and what feeds it.
  3. Curio writes the chart into the node, for everyone in the dataflow, and the chat shows the change with its Undo.

The Agent Catalog reference lists every agent's prompts, walks through more examples, and describes the three helpers that only have modes.