Terraform

The Terraform provider manages what Agents as code, Tools and credentials and Evaluations in your pipeline do through the API, so one terraform apply can put a customer's whole setup in place and the next one shows what changed in the console since.

Two data sources read what you do not manage: aigently_project, found by its name, and aigently_agent, by its id.

Getting it

The provider will be published to the Terraform Registry, as aigently/aigently, with our other SDKs. Until then, every resource here is a request you can make yourself, and the guides linked above show each one.

The key it needs

A live key (Keys), in AIGENTLY_API_KEY or the provider's api_key, holding what your configuration uses: agents:read and agents:write for agents, tools:write for tools and MCP servers, vault:write for credentials — which only an owner can give a key — evaluations:run with agents:write for evaluations, and webhooks:read and webhooks:write for receivers.

A configuration

terraform {
  required_providers {
    aigently = { source = "aigently/aigently" }
  }
}

provider "aigently" {}

variable "orders_api_token" {
  type      = string
  sensitive = true
}

data "aigently_project" "front" {
  name = "Front desk"
}

resource "aigently_vault_secret" "orders" {
  name              = "Orders API"
  secret_wo         = var.orders_api_token
  secret_wo_version = 1
  project_ids       = [data.aigently_project.front.id]
}

resource "aigently_tool" "lookup_order" {
  project_id  = data.aigently_project.front.id
  name        = "lookup_order"
  description = "Look up the status of an order by its number."
  parameters  = jsonencode({ type = "object", properties = { order_id = { type = "string" } } })
  http = jsonencode({
    method = "GET"
    url    = "https://orders.aigently.ai/v1/orders/{order_id}"
    auth   = { type = "bearer", vault_key_id = aigently_vault_secret.orders.id }
  })
}

resource "aigently_agent" "front_desk" {
  project_id = data.aigently_project.front.id
  definition = jsonencode(merge(
    jsondecode(file("front-desk.json")),
    { references = { tools = [aigently_tool.lookup_order.name] } },
  ))
  publish = true
}

front-desk.json is the file the console exports from the agent's menu, or what GET /v1/agents/{id}/definition answers.

How a change shows in a plan

• A definition is compared for what it says. The API fills in every default a definition leaves out, and none of those is a change. A value edited in the console is: the plan shows that one value going back to what you wrote.
• Name a tool through its resource, as above, so Terraform makes the tool before the agent. A definition that names something the project does not have is applied without it, with a warning, and the plan keeps showing it until the project has it.
• A definition for another kind or direction of agent makes a new agent, because an agent keeps both for its whole life.
• Header values and an MCP server's address are hidden when they are read, and the provider keeps what you configured rather than the hidden form, so they show no change.

Publishing

With publish = true, every change is published through the console's own Publish check, and published_version is the version it made — what Pin a version pins a conversation to. A refused publish fails the apply with every reason. On an existing agent, the next apply publishes again; a new agent stays made, and Terraform marks it tainted, so run terraform untaint once the reasons are fixed to keep it.

Credentials

secret_wo sends a credential's value without Terraform ever keeping it, and sends it again when you raise secret_wo_version. It needs Terraform 1.11 or later. secret works with any version, and Terraform keeps it in its state, as it does every sensitive value. Either way, a value replaced in the console is noticed from its last four characters, and the next apply puts yours back.

Importing

Each resource imports by its id: terraform import aigently_agent.front_desk 8a1f3c2e-…. An evaluation imports as <agent_id>/<evaluation_id>. Values a read hides — a tool's headers, a credential, a receiver's signing secret — are not imported. The first plan after an import shows a tool's hidden values being set, and a receiver's secret stays empty until it is made again.