Agents

import { Shadway, ShadwayTimeoutError, isKnownEvent } from "shadway";

const shadway = new Shadway();
const model = process.env.SHADWAY_MODEL;
if (!model) throw new Error("Set SHADWAY_MODEL");

const capabilities = [
  "email.send",
  "email.get_delivery",
  "mailbox.read_thread",
  "mailbox.reply",
  "procurement.create_po",
  "shipping.get_status",
];

const agent = await shadway.agents.create({
  name: "Operations",
  model,
  instructions: [
    "Compare supplier prices and delivery dates.",
    "Ask for written confirmation of agreed terms.",
    "Follow up when a supplier misses a promised response.",
    "Report missing information instead of guessing.",
  ].join("\n"),
  capabilities,
  metadata: { team: "procurement" },
});

console.log(agent.id); // Save this ID in your application.

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	shadway "github.com/shadwayhq/shadway-go"
)

var capabilities = []string{
	"email.send",
	"email.get_delivery",
	"mailbox.read_thread",
	"mailbox.reply",
	"procurement.create_po",
	"shipping.get_status",
}

func main() {
	client, err := shadway.New()
	if err != nil {
		log.Fatal(err)
	}
	ctx := context.Background()

	model := os.Getenv("SHADWAY_MODEL")
	if model == "" {
		log.Fatal("Set SHADWAY_MODEL")
	}

	instructions := "Compare supplier prices and delivery dates.\n" +
		"Ask for written confirmation of agreed terms.\n" +
		"Follow up when a supplier misses a promised response.\n" +
		"Report missing information instead of guessing."

	agent, err := client.Agents.Create(ctx, shadway.AgentCreateParams{
		Name:         "Operations",
		Model:        model,
		Instructions: &instructions,
		Capabilities: capabilities,
		Metadata:     &shadway.Metadata{"team": "procurement"},
	})
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(agent.ID) // Save this ID in your application.
}

const savedAgent = await shadway.agents.get(agent.id);

console.log(savedAgent.name, savedAgent.model, savedAgent.status);

const capabilityStatus = savedAgent.capabilityStatus ?? {};
for (const [name, readiness] of Object.entries(capabilityStatus)) {
  if (readiness.status !== "ready") {
    throw new Error(
      name + ": " + readiness.status + ": " + (readiness.detail ?? ""),
    );
  }
}

const requiredCustom = new Set([
  "procurement.create_po",
  "shipping.get_status",
]);

for await (const capability of shadway.capabilities.list()) {
  if (
    requiredCustom.has(capability.name) &&
    capability.status === "active" &&
    capability.executionMode === "available"
  ) {
    requiredCustom.delete(capability.name);
  }
}

if (requiredCustom.size > 0) {
  throw new Error("Connect executors for: " + [...requiredCustom].join(", "));
}

savedAgent, err := client.Agents.Get(ctx, agent.ID)
if err != nil {
	log.Fatal(err)
}

fmt.Println(savedAgent.Name, savedAgent.Model, savedAgent.Status)

if savedAgent.CapabilityStatus != nil {
	for name, readiness := range *savedAgent.CapabilityStatus {
		if readiness.Status != shadway.AgentCapabilityReadinessReady {
			detail := ""
			if readiness.Detail != nil {
				detail = *readiness.Detail
			}
			log.Fatalf("%s: %s: %s", name, readiness.Status, detail)
		}
	}
}

requiredCustom := map[string]bool{
	"procurement.create_po": true,
	"shipping.get_status":   true,
}

for capability, err := range client.Capabilities.List(ctx, nil) {
	if err != nil {
		log.Fatal(err)
	}
	if requiredCustom[capability.Name] &&
		capability.Status == shadway.CapabilityStatusActive &&
		capability.ExecutionMode == shadway.CapabilityExecutionModeAvailable {
		delete(requiredCustom, capability.Name)
	}
}

if len(requiredCustom) > 0 {
	log.Fatalf("Connect executors for: %v", requiredCustom)
}

const deadline = process.env.DELIVERY_DEADLINE;
if (
  !deadline ||
  !Number.isFinite(Date.parse(deadline)) ||
  Date.parse(deadline) <= Date.now()
) {
  throw new Error("Set DELIVERY_DEADLINE to a future RFC 3339 timestamp");
}

const mandate = await shadway.mandates.create({
  agent: agent.id,
  objective:
    "Buy 200 units of part #48-221 for less than $8,000 total, " +
    "including shipping. Confirm delivery by " + deadline + ".",
  guidance: [
    "Request quotes from sales@atlas.example, sales@beacon.example, " +
      "and sales@cedar.example.",
    "Include quantity, shipping cost, and delivery date in each request.",
    "Wait up to 24 hours for replies, then follow up with missing suppliers.",
    "Compare the quotes and negotiate before requesting purchase approval.",
    "After ordering, check shipment status and contact the supplier if delayed.",
  ],
  deadline: new Date(deadline),
  authority: {
    capabilities,
    spend: {
      maximum: { amount: 799_999, currency: "usd" },
    },
    maximumActions: 40,
    maximumReadActions: 100,
    capabilityLimits: [
      { capability: "procurement.create_po", maximumActions: 1 },
    ],
    approval: {
      requiredFor: ["procurement.create_po"],
    },
    successCriteria: [
      { fact: "amount_minor", max: 799_999 },
      { fact: "delivered", equals: true },
    ],
  },
  metadata: { purchaseRequest: "PR-1042" },
});

const work = shadway.mandate(mandate.id);
console.log(work.id); // Save this ID to reconnect later.

deadlineRaw := os.Getenv("DELIVERY_DEADLINE")
deadline, err := time.Parse(time.RFC3339, deadlineRaw)
if err != nil || !deadline.After(time.Now()) {
	log.Fatal("Set DELIVERY_DEADLINE to a future RFC 3339 timestamp")
}

maxActions := int64(40)
maxReadActions := int64(100)
poLimit := int64(1)
maxAmount := float64(799_999)
due := shadway.NullableTimestamp(&deadline)

mandate, err := client.Mandates.Create(ctx, shadway.MandateCreateParams{
	Agent: agent.ID,
	Objective: "Buy 200 units of part #48-221 for less than $8,000 total, " +
		"including shipping. Confirm delivery by " + deadlineRaw + ".",
	Guidance: []string{
		"Request quotes from sales@atlas.example, sales@beacon.example, " +
			"and sales@cedar.example.",
		"Include quantity, shipping cost, and delivery date in each request.",
		"Wait up to 24 hours for replies, then follow up with missing suppliers.",
		"Compare the quotes and negotiate before requesting purchase approval.",
		"After ordering, check shipment status and contact the supplier if delayed.",
	},
	Deadline: &due,
	Authority: &shadway.Authority{
		Capabilities: capabilities,
		Spend: &shadway.SpendAuthority{
			Maximum: shadway.Money{Amount: 799_999, Currency: "usd"},
		},
		MaximumActions:     &maxActions,
		MaximumReadActions: &maxReadActions,
		CapabilityLimits: []shadway.CapabilityLimit{
			{Capability: "procurement.create_po", MaximumActions: &poLimit},
		},
		Approval: &shadway.ApprovalAuthority{
			RequiredFor: []string{"procurement.create_po"},
		},
		SuccessCriteria: []shadway.SuccessCriterion{
			{Fact: "amount_minor", Max: &maxAmount},
			{Fact: "delivered", Equals: true},
		},
	},
	Metadata: &shadway.Metadata{"purchaseRequest": "PR-1042"},
})
if err != nil {
	log.Fatal(err)
}

work := client.Mandate(mandate.ID)
fmt.Println(work.ID()) // Save this ID to reconnect later.

async function monitor(mandateId: string, signal: AbortSignal) {
  const handle = shadway.mandate(mandateId);
  const current = await handle.get();
  console.log(current.status, current.currentState);
  if (["completed", "failed", "canceled", "expired"].includes(current.status)) {
    return;
  }

  for await (const event of handle.events.stream({ signal })) {
    if (!isKnownEvent(event)) continue;

    console.log(event.id, event.type, event.data);

    if (
      event.type === "mandate.status_changed" &&
      ["completed", "failed", "canceled", "expired"].includes(
        event.data.mandate.status,
      )
    ) {
      break;
    }
  }
}

func monitor(ctx context.Context, client *shadway.Client, mandateID string) error {
	handle := client.Mandate(mandateID)
	current, err := handle.Get(ctx)
	if err != nil {
		return err
	}
	fmt.Println(current.Status, current.CurrentState)
	switch current.Status {
	case shadway.MandateStatusCompleted, shadway.MandateStatusFailed,
		shadway.MandateStatusCanceled, shadway.MandateStatusExpired:
		return nil
	}

	for event, err := range handle.Stream(ctx, shadway.EventStreamOptions{}) {
		if err != nil {
			return err
		}
		if !event.IsKnown() {
			continue
		}

		fmt.Println(event.ID, event.Type, event.Data)

		if data, ok := event.Data.(*shadway.MandateStatusChangedData); ok {
			switch data.Mandate.Status {
			case shadway.MandateStatusCompleted, shadway.MandateStatusFailed,
				shadway.MandateStatusCanceled, shadway.MandateStatusExpired:
				return nil
			}
		}
	}
	return nil
}

try {
  const approval = await work.waitForApproval({ timeout: "30m" });

  if (approval) {
    // Present these fields in your application's approval screen.
    console.log({
      id: approval.id,
      question: approval.question,
      action: approval.action,
      expiresAt: approval.expiresAt,
    });
  } else {
    console.log("The mandate ended without a pending approval.");
  }
} catch (error) {
  if (!(error instanceof ShadwayTimeoutError)) throw error;
  console.log("No approval yet. The mandate continues on the server.");
}

approval, err := work.WaitForApproval(ctx, shadway.WaitOptions{
	Timeout: 30 * time.Minute,
})
if err != nil {
	if shadway.IsTimeout(err) {
		fmt.Println("No approval yet. The mandate continues on the server.")
		return
	}
	log.Fatal(err)
}

if approval == nil {
	fmt.Println("The mandate ended without a pending approval.")
	return
}

// Present these fields in your application's approval screen.
fmt.Println(approval.ID, approval.Question)
fmt.Println(approval.Action.Capability, approval.Action.Consequence)
fmt.Println(approval.ExpiresAt)

async function decidePurchase(
  approvalId: string,
  mandateId: string,
  decision: "approve" | "reject",
  reason: string,
) {
  const approval = await shadway.approvals.get(approvalId);
  if (approval.mandate !== mandateId || approval.status !== "pending") {
    throw new Error("This approval is not pending for this mandate");
  }

  if (decision === "approve") {
    return shadway.approvals.approve(approval.id, { reason });
  }
  return shadway.approvals.reject(approval.id, { reason });
}

func decidePurchase(ctx context.Context, client *shadway.Client, approvalID, mandateID, decision, reason string) (*shadway.Approval, error) {
	approval, err := client.Approvals.Get(ctx, approvalID)
	if err != nil {
		return nil, err
	}
	if approval.Mandate != mandateID || approval.Status != shadway.ApprovalStatusPending {
		return nil, errors.New("this approval is not pending for this mandate")
	}

	if decision == "approve" {
		return client.Approvals.Approve(ctx, approval.ID, &shadway.ApprovalApproveParams{Reason: &reason})
	}
	return client.Approvals.Reject(ctx, approval.ID, &shadway.ApprovalRejectParams{Reason: &reason})
}

try {
  const result = await work.wait({ timeout: "30m" });
  console.log(result.status, result.currentState.summary);

  if (result.status === "completed") {
    for await (const fact of work.facts.list()) {
      console.log("Fact", fact);
    }
    for await (const evidence of work.evidence.list()) {
      console.log("Evidence", evidence);
    }
  } else {
    console.log("The task ended without completing the objective.");
    for await (const issue of work.issues.list()) {
      console.log("Issue", issue);
    }
  }
} catch (error) {
  if (!(error instanceof ShadwayTimeoutError)) throw error;
  console.log("Still waiting. Reconnect later with mandate ID:", work.id);
}

result, err := work.Wait(ctx, shadway.WaitOptions{Timeout: 30 * time.Minute})
if err != nil {
	if shadway.IsTimeout(err) {
		fmt.Println("Still waiting. Reconnect later with mandate ID:", work.ID())
		return
	}
	log.Fatal(err)
}
fmt.Println(result.Status, result.CurrentState.Summary)

if result.Status == shadway.MandateStatusCompleted {
	for fact, err := range work.Facts(ctx, nil) {
		if err != nil {
			log.Fatal(err)
		}
		fmt.Println("Fact", fact)
	}
	for evidence, err := range work.Evidence(ctx, nil) {
		if err != nil {
			log.Fatal(err)
		}
		fmt.Println("Evidence", evidence)
	}
} else {
	fmt.Println("The task ended without completing the objective.")
	for issue, err := range work.Issues(ctx, nil) {
		if err != nil {
			log.Fatal(err)
		}
		fmt.Println("Issue", issue)
	}
}

async function pausePurchase(mandateId: string) {
  return shadway.mandate(mandateId).pause({
    reason: "Procurement is reviewing the specification.",
  });
}

async function resumePurchase(mandateId: string) {
  return shadway.mandate(mandateId).resume({
    reason: "The specification is confirmed.",
  });
}

async function cancelPurchase(mandateId: string) {
  return shadway.mandate(mandateId).cancel({
    reason: "The part is no longer needed.",
  });
}

func pausePurchase(ctx context.Context, client *shadway.Client, mandateID string) (*shadway.Mandate, error) {
	reason := "Procurement is reviewing the specification."
	return client.Mandate(mandateID).Pause(ctx, &shadway.MandateCommandParams{Reason: &reason})
}

func resumePurchase(ctx context.Context, client *shadway.Client, mandateID string) (*shadway.Mandate, error) {
	reason := "The specification is confirmed."
	return client.Mandate(mandateID).Resume(ctx, &shadway.MandateCommandParams{Reason: &reason})
}

func cancelPurchase(ctx context.Context, client *shadway.Client, mandateID string) (*shadway.Mandate, error) {
	reason := "The part is no longer needed."
	return client.Mandate(mandateID).Cancel(ctx, &shadway.MandateCommandParams{Reason: &reason})
}

const revisedAgent = await shadway.agents.update(agent.id, {
  instructions: [
    "Compare supplier prices and delivery dates.",
    "Request a backup delivery option for urgent orders.",
    "Ask for written confirmation of agreed terms.",
    "Report missing information instead of guessing.",
  ].join("\n"),
});

for await (const item of shadway.agents.list({ limit: 20 })) {
  console.log(item.id, item.name, item.status);
}

console.log(revisedAgent.id); // Same agent ID, updated configuration.

revisedInstructions := "Compare supplier prices and delivery dates.\n" +
	"Request a backup delivery option for urgent orders.\n" +
	"Ask for written confirmation of agreed terms.\n" +
	"Report missing information instead of guessing."

revisedAgent, err := client.Agents.Update(ctx, agent.ID, shadway.AgentUpdateParams{
	Instructions: &revisedInstructions,
})
if err != nil {
	log.Fatal(err)
}

for item, err := range client.Agents.List(ctx, &shadway.ListParams{Limit: 20}) {
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(item.ID, item.Name, item.Status)
}

fmt.Println(revisedAgent.ID) // Same agent ID, updated configuration.

async function disableAgent(agentId: string) {
  return shadway.agents.update(agentId, { status: "disabled" });
}

async function enableAgent(agentId: string) {
  return shadway.agents.update(agentId, { status: "active" });
}

func disableAgent(ctx context.Context, client *shadway.Client, agentID string) (*shadway.Agent, error) {
	status := shadway.AgentStatusDisabled
	return client.Agents.Update(ctx, agentID, shadway.AgentUpdateParams{Status: &status})
}

func enableAgent(ctx context.Context, client *shadway.Client, agentID string) (*shadway.Agent, error) {
	status := shadway.AgentStatusActive
	return client.Agents.Update(ctx, agentID, shadway.AgentUpdateParams{Status: &status})
}

const updated = await shadway.agents.update(agent.id, {
  capabilities: [
    "email.send",
    "email.get_delivery",
    "mailbox.read_thread",
    "mailbox.reply",
    "phone.call",
    "phone.get_call",
    "phone",
  ],
  capabilityConfig: {
    phone: { country: "US", areaCode: "302" },
  },
});

country := "US"
areaCode := "302"

updated, err := client.Agents.Update(ctx, agent.ID, shadway.AgentUpdateParams{
	Capabilities: []string{
		"email.send",
		"email.get_delivery",
		"mailbox.read_thread",
		"mailbox.reply",
		"phone.call",
		"phone.get_call",
		"phone",
	},
	CapabilityConfig: &shadway.AgentCapabilityConfigMap{
		"phone": {Country: &country, AreaCode: &areaCode},
	},
})
if err != nil {
	log.Fatal(err)
}

fmt.Println(updated.ID) // Same agent, new configuration revision.

await shadway.agents.update(agent.id, {
  instructions:
    "Be concise with suppliers. Record every concession. " +
    "Require written confirmation of agreed terms.",
});

concise := "Be concise with suppliers. Record every concession. " +
	"Require written confirmation of agreed terms."

if _, err := client.Agents.Update(ctx, agent.ID, shadway.AgentUpdateParams{
	Instructions: &concise,
}); err != nil {
	log.Fatal(err)
}