Overview

In AgentScope AI, agents are autonomous entities that leverage advanced AI models to execute a sequence of actions for complex security and auditing tasks. Unlike one-off tools, these agents function as persistent assistants that can interact with external systems, invoke custom functions, and integrate with various APIs to provide continuous security insights and risk assessments. This document outlines how to create, configure, and interact with agents within the AgentScope AI ecosystem.

1. Creating and Configuring Agents

Agents in AgentScope AI are created using the Agent class. Each agent is configured with a unique name, specific instructions, and the chosen language model provider. This configuration enables the agent to perform its designated security audit tasks effectively.

Example: Creating an Agent

typescript // File: src/agents/index.ts
import { Agent } from "@agentscope/core";

export const securityAgent = new Agent({
  name: "Security Agent",
  instructions: "You are an expert security auditor focused on smart contract analysis.",
  model: {
    provider: "AgentScope AI",   // Example provider
    name: "Model-001",         // Model name can be adjusted based on requirements
  },
});

Environment Setup

Ensure that all necessary environment variables, such as your API keys, are set in the .env file:

dotenv // File: .env
AgentScope_AI_API_KEY=your_agentscope_ai_api_key

Install the required package:

bash
npm install @agentscope/core

2. Registering the Agent

Once an agent is created, it must be registered with the AgentScope AI system to enable logging, access to configured tools, and integration with third-party services.

Example: Registering the Agent

typescript // File: src/index.ts
import { AgentScope } from "@agentscope/core";
import { securityAgent } from "./agents";

export const agentscope = new AgentScope({
  agents: { securityAgent },
});

3. Generating and Streaming Text

Agents can generate responses to user queries using the .generate() method, which processes a series of messages and returns a text output. For more interactive applications, responses can also be streamed in real time.

Generating Text Example

typescript // File: src/index.ts
const response = await securityAgent.generate([
  { role: "user", content: "Explain the vulnerabilities in our latest smart contract." },
]);

console.log("Agent Response:", response.text);

Streaming Responses Example

typescript // File: src/index.ts
const stream = await securityAgent.stream([
  { role: "user", content: "Provide a detailed analysis of the security risks." },
]);

for await (const chunk of stream.textStream) {
  process.stdout.write(chunk);
}

4. Structured Output

Agents can return structured data by using a JSON Schema or a Zod schema. This ensures that the output is both predictable and type-safe.

Using JSON Schema

typescript
const schema = {
  type: "object",
  properties: {
    summary: { type: "string" },
    riskFactors: { type: "array", items: { type: "string" } },
  },
  additionalProperties: false,
  required: ["summary", "riskFactors"],
};

const structuredResponse = await securityAgent.generate(
  [
    {
      role: "user",
      content: "Provide a summary of the risk factors for the following contract code: ...",
    },
  ],
  { output: schema }
);

console.log("Structured Output:", structuredResponse.object);

Using Zod Schema

typescript
import { z } from "zod";

const zSchema = z.object({
  summary: z.string(),
  riskFactors: z.array(z.string()),
});

const structuredResponseZod = await securityAgent.generate(
  [
    {
      role: "user",
      content: "Provide a summary and list of risk factors for the provided smart contract.",
    },
  ],
  { output: zSchema }
);

console.log("Structured Output:", structuredResponseZod.object);

5. Running Agents

AgentScope AI provides a CLI tool to run your agents behind an API. By default, the CLI looks for agents in the src/agents directory.

Starting the Agent Server

bash
agentscope dev

This command starts the server, making your agents accessible at an endpoint such as http://localhost:4111/api/agents/securityAgent/generate.

6. Interacting with Agents

You can interact with your agent through standard HTTP requests. For example, using curl:

bash
curl -X POST http://localhost:4111/api/agents/securityAgent/generate \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "How can you improve the security of our smart contract?" }
    ]
  }'